STJ 0.6.0

[yaniv-golan]

Standard Transcription JSON (STJ) v0.6.0

This release includes several breaking changes and significant improvements to the specification, focusing on validation requirements and implementation clarity.

Breaking Changes ⚠️

Please be aware of the following breaking changes that require implementation updates:

File Extensions

• Primary recommended extension changed from .stj.json to .stjson
• Implementations should:
  • Use .stjson as default for new files
  • Support .stj and .stj.json as alternatives
  • Maintain backward compatibility with .stj.json

Root Structure

• version field moved from metadata section to root stj object
• New required root structure:

{
  "stj": {
    "version": "0.6.0",
    "metadata": { ... },
    "transcript": { ... }
  }
}

• No additional properties allowed at root level

Character Encoding

• UTF-8 Byte Order Mark (BOM) now prohibited
• Files MUST be encoded in UTF-8 without BOM

Major Improvements 🚀

Validation Framework

• Introduced structured validation with severity levels:
  • ERROR: File must be rejected
  • WARNING: Processing may continue with caution
  • INFO: Suggestions and notifications
• Added standardized validation response format
• Specified validation sequence requirements
• Added error recovery guidelines

Empty Value Handling

• Clear rules for empty arrays, objects, and strings
• Explicit specifications for which fields may be empty vs omitted
• Defined validation requirements for empty value handling

Time Value Processing

• IEEE 754 round-to-nearest-even for values > 3 decimal places
• Preserved precision up to 3 decimal places
• Enhanced zero-duration handling with is_zero_duration field

Additional Changes 📝

Metadata

• metadata section is now optional
• Removed ordering constraints in JSON objects
• Enhanced guidance for custom namespace usage in extensions

Validation Requirements

• Added structured validation response format
• Required collection of multiple validation issues
• Specified validation sequence and error recovery strategies

RFC 2119 Keywords

• Added explicit definitions for requirement levels (MUST, SHOULD, etc.)
• Ensured consistent usage throughout specification

Migration Guide 🔄

For Implementers

1. File Extensions

   • Update file creation to use .stjson by default
   • Ensure your implementation recognizes all supported extensions

2. Root Structure

   • Move version field to root stj object
   • Update parsers to validate new root structure
   • Ensure no additional root properties

3. Validation

   • Implement new severity levels
   • Update validation to collect multiple issues
   • Add structured validation response format
   • Follow specified validation sequence

4. Empty Values

   • Review empty value handling
   • Update validation for empty arrays/objects
   • Implement proper field omission

5. Time Values

   • Implement IEEE 754 rounding
   • Update zero-duration handling
   • Preserve time value precision

For File Authors

1. Use .stjson extension for new files
2. Follow new root structure with stj object
3. Omit BOM from UTF-8 encoding
4. Omit metadata section if not needed
5. Follow empty value guidelines

Documentation 📚

Full specification and documentation available at:
STJ Specification v0.6.0

Feedback and Support 💬

I welcome your feedback and questions! Please open issues on GitHub for:

• Bug reports
• Feature requests
• Implementation questions
• Documentation improvements

---

This discussion was created from the release STJ 0.6.0.