Document Metadata structure #861
Conversation
reinecke
left a comment
reinecke
left a comment
There was a problem hiding this comment.
This is a good add! Just a couple small notes about clarification.
| Due to the fact that many different workflows can and will use metadata, it is important to group your | ||
| metadata inside a namespace so that all of those can coexist without stomping on each other. In the example below, you can see that there is metadata on the Timeline and on several Clips for both a hypothetical `my_playback_tool` and `my_production_tracking_system` that could coexist with anything else you add under a similar namespace. | ||
|
|
||
| Metadata can also be useful when prototyping new OTIO schemas. An existing object can be extended with metadata which can later be upgraded into a new schema version, or a schemadef plugin. |
There was a problem hiding this comment.
Perhaps "migrated into top-level attributes on a new schema version" would be clearer than "upgraded" to convey that the data should move out of the metadata dictionary and on to "top-level" properties.
ssteinbach
left a comment
ssteinbach
left a comment
There was a problem hiding this comment.
- remove "you"
- one question regarding connecting up with the autogeneration system
- some wording tweaks
let me know what you think
| This may be out of date. | ||
|
|
||
| This DRAFT describes the OpenTimelineIO JSON File Format as of OTIO Alpha 5. | ||
| This DRAFT describes the OpenTimelineIO JSON File Format as of OTIO Beta 13. |
There was a problem hiding this comment.
Is there a way to embed this into the automatically generated document? Otherwise we should add to our release process updating this document.
There was a problem hiding this comment.
Given that we didn't actually update the contents of this since Alpha 5, I think it was correct. We should add a manual process to any schema enhancements to include documentation.
There was a problem hiding this comment.
Sorry, to include updating the documentation? Or to include documentation in general?
Either way, we should keep a list of which pages to check then. We can add a todo to our TSC documentation pass list.
There was a problem hiding this comment.
I think both. Specifically any PR that changes schema should update this document (in addition to the autogenerated one) - and when we do a release, we should have a reminder "check that the file format spec documentation reflects any schema changes" in case we missed anything important.
Co-authored-by: Stephan Steinbach <61017+ssteinbach@users.noreply.github.com>
|
I removed all other instances of "you" and "we" from the document. Phrasing suggestions welcome :) |
|
lgtm, thanks @jminor! |
3 participants
This PR adds documentation about how metadata should be nested inside a namespace.