Skip to content

Generate the OTIO Core Specification from code + curated overlay - #2024

Open
jhodges10 wants to merge 4 commits into
AcademySoftwareFoundation:mainfrom
jhodges10:jh/generate-core-specification
Open

jhodges10 wants to merge 4 commits into
AcademySoftwareFoundation:mainfrom
jhodges10:jh/generate-core-specification

Conversation

@jhodges10

Copy link
Copy Markdown
Collaborator

Summary

This is a first step toward generating the OTIO Core Specification from the code rather than maintaining it by hand. It adds a generator that assembles a full specification document from two sources:

  1. The code — every serializable schema object, its fields, field types, default values, inheritance, and the semantic docstrings carried by the bindings.
  2. A curated markdown overlay — the human-authored narrative (intro, conventions, the metadata dictionary, root objects, JSON serialization) and the per-object integrator usage guidance that doesn't belong in terse API docstrings.

The per-object semantic definitions live in the binding docstrings (single source of truth, also improves IDE/readthedocs help); the narrative and usage guidance live in the overlay. The generator interleaves them.

What's here

  • Enriches autogen_serialized_datamodel.py so the serialized-schema docs now carry per-field type info (derived from the pybind11 getter signatures, normalized to spec vocabulary — String, Double, Array[Effect], Map[String, MediaReference], TimeRange, …), optional flags, default values, and a class-level inheritance chain. (Resolves the long-standing # @TODO: having type information here would be awesome.)
  • Adds autogen_core_specification.py, which reuses that model and stitches it together with a curated overlay to produce docs/spec/otio-core-specification.md. The overlay (docs/spec/core-specification-overlay.md) is plain markdown with HTML-comment directives (@preamble / @section / @object / @appendix), parsed with the stdlib — no new dependencies.
  • Completeness contract: generation fails unless every non-plugin schema object is documented by exactly one @object entry. Adding a new schema to the code forces a matching overlay entry, so the spec can't silently drift.
  • Fills in missing per-field semantic docstrings on the otio and opentime bindings (e.g. source_range, kind, global_start_time, available_range, target_url, RationalTime.value/rate, TimeRange.start_time/duration, name/metadata). These flow into both the serialized-schema docs and the specification.
  • Tooling: make spec / make spec-update, plus a regenerate-and-compare unit test (CoreSpecificationTester) matching the existing autogen-doc pattern.

Regenerating

make spec-update         # regenerate docs/spec/otio-core-specification.md
make doc-model-update    # regenerate the serialized-schema docs

Edit prose in docs/spec/core-specification-overlay.md; edit field/object definitions in the bindings.

Testing

  • CoreSpecificationTester, SerializedSchemaTester, and PluginDocumentationTester pass.
  • Core functional tests (clip / marker / transition / timeline / opentime / color) pass — the binding changes are docstrings only.

Notes

  • The binding docstring additions require a recompile before regenerating the docs, since the generator reads docstrings from the compiled module.
  • Follow-ups worth considering: cardinality indicators (0..1 / 0..*), per-property "inherited from" grouping, intra-document cross-links between object headings, and UML/diagrams.

@timlehr

timlehr commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Hey @jhodges10, can you please rebase the branch, there were some CI issues we have resolved now.

@jhodges10

Copy link
Copy Markdown
Collaborator Author

Hey @jhodges10, can you please rebase the branch, there were some CI issues we have resolved now.

Sure thing!

@meshula

meshula commented Aug 29, 2026

Copy link
Copy Markdown
Collaborator

I can see a ton of value in adapting this into a validation check. It could drive automation that could discover or bring attention to drift between the spec and the implementation. My feeling though is that the spec itself should be hand authored for clarity & to ensure intentionality. (Intentionality meaning, something in the spec is meant to be there, as opposed to propagated up from an implementation detail.)

This adds a generator that assembles the OpenTimelineIO Core Specification
from two sources: the code (every serializable schema object, its fields,
field types, default values, inheritance, and binding docstrings) and a
curated markdown overlay holding the human-authored narrative and per-object
integrator usage guidance.

Changes:

- Enrich autogen_serialized_datamodel.py so the serialized-schema docs now
  carry per-field type info (derived from pybind11 getter signatures,
  normalized to spec vocabulary), optional flags, default values, and a
  class-level inheritance chain. Addresses the long-standing "type information
  would be awesome" TODO.

- Add autogen_core_specification.py, which reuses that model and interleaves it
  with docs/spec/core-specification-overlay.md to produce a full specification
  document (docs/spec/otio-core-specification.md). The overlay is plain markdown
  with HTML-comment directives, parsed with the stdlib (no new dependencies).
  Generation fails unless every non-plugin schema object is documented exactly
  once, so the spec cannot silently drift from the code.

- Fill in the missing per-field semantic docstrings on the bindings (otio and
  opentime) so the pure definitions live in code and flow into both the
  serialized-schema docs and the specification.

- Wire up `make spec` / `make spec-update` and a regenerate-and-compare unit
  test (CoreSpecificationTester), matching the existing autogen doc pattern.

Signed-off-by: Jeff Hodges <jeff@jeffhq.com>
@jhodges10
jhodges10 force-pushed the jh/generate-core-specification branch from e9a11de to a6f63cc Compare October 30, 2026 19:16
@jhodges10

jhodges10 commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator Author

I can see a ton of value in adapting this into a validation check. It could drive automation that could discover or bring attention to drift between the spec and the implementation. My feeling though is that the spec itself should be hand authored for clarity & to ensure intentionality. (Intentionality meaning, something in the spec is meant to be there, as opposed to propagated up from an implementation detail.)

@meshula I agree with you here in principle, but it would probably be nice to have some tooling that make that a little simpler.

What about writing the spec using JSON Schema and leveraging some of the tooling around that?

@codecov-commenter

codecov-commenter commented Oct 30, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 85.42274% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.63%. Comparing base (0bfd9d6) to head (96fc21c).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
...entimelineio/console/autogen_core_specification.py 80.62% 19 Missing and 6 partials ⚠️
...timelineio/console/autogen_serialized_datamodel.py 84.25% 12 Missing and 8 partials ⚠️
...entimelineio-bindings/otio_serializableObjects.cpp 84.84% 5 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #2024      +/-   ##
==========================================
+ Coverage   83.62%   83.63%   +0.01%     
==========================================
  Files         184      185       +1     
  Lines       13627    13924     +297     
  Branches     1270     1332      +62     
==========================================
+ Hits        11395    11646     +251     
- Misses       2059     2092      +33     
- Partials      173      186      +13     
Flag Coverage Δ
py-unittests 83.63% <85.42%> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
...lineio/opentime-bindings/opentime_rationalTime.cpp 87.03% <100.00%> (ø)
...imelineio/opentime-bindings/opentime_timeRange.cpp 99.00% <100.00%> (ø)
...ineio/opentime-bindings/opentime_timeTransform.cpp 96.87% <100.00%> (ø)
tests/test_serialized_schema.py 97.82% <100.00%> (+2.27%) ⬆️
...entimelineio-bindings/otio_serializableObjects.cpp 84.03% <84.84%> (-0.43%) ⬇️
...timelineio/console/autogen_serialized_datamodel.py 82.04% <84.25%> (+2.93%) ⬆️
...entimelineio/console/autogen_core_specification.py 80.62% <80.62%> (ø)

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0bfd9d6...96fc21c. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jhodges10 and others added 3 commits October 30, 2026 15:07
Signed-off-by: Jeff Hodges <jeff.hodges@hodgesbadge.com>
Signed-off-by: Jeff Hodges <jeff@jeffhq.com>
Signed-off-by: Jeff Hodges <jeff@jeffhq.com>
@jhodges10
jhodges10 force-pushed the jh/generate-core-specification branch from e1c0a4e to 96fc21c Compare October 30, 2026 20:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants