Skip to content

fix(spec): schema field description omits load() - #80

Open
ficosta wants to merge 1 commit into
ebu:mainfrom
ficosta:fix/schema-description-method-names
Open

fix(spec): schema field description omits load()#80
ficosta wants to merge 1 commit into
ebu:mainfrom
ficosta:fix/schema-description-method-names

Conversation

@ficosta

@ficosta ficosta commented Aug 26, 2026

Copy link
Copy Markdown

The schema field in the Graphic Manifest is described as defining "the data
parameters of the 'update' method". The specification describes the same field
differently in Specification.md line 74, as "the JSON schema definition for the
data argument to the load() and updateAction() methods".

The substantive problem is the omission of load(). This schema governs the data
argument passed to load() as well as the one passed to updateAction().
Specification.md lines 263 to 265 state it directly: the data given to load()
"follows the model described in the Manifest using the schema field". As written,
the description suggests the schema only applies to the update path, which could lead
an implementation to validate data on update but not on load, or a controller to
offer schema-driven input only for updates.

The method name is the smaller issue, since 'update' was presumably meant as
updateAction(). Still, no method by that name exists: the Graphic methods are
load(), dispose(), playAction(), stopAction(), updateAction(),
customAction(), and, for non-real-time Graphics, goToTime() and
setActionsSchedule(), and the Server API graphicInstance operations are clear,
load, updateAction, playAction, stopAction and
customActions/{customActionId}.

This is not only an internal inconsistency. server-api.yaml references
graphics/schema.json by $ref, so the string is generated into both committed
definition files and ships in the published package. In ograf@1.2.0 it appears at
dist/generated/graphics-manifest.d.ts:401 and dist/generated/server-api.d.ts:1568,
which means anyone implementing OGraf sees it as an editor tooltip on the schema
field, pointing at a method that does not exist.

The line dates back to the initial import of the documentation and appears to predate
the current method naming.

What changed

The description now reads "the data parameters of the 'load()' and 'updateAction()'
methods", matching Specification.md and following the convention already used in
this file, where supportsNonRealTime refers to "the 'goToTime()' and the
'setActionsSchedule()' methods".

Three lines, one per file:

  • v1/specification/json-schemas/graphics/schema.json (the source)
  • v1/typescript-definitions/src/generated/graphics-manifest.ts (regenerated)
  • v1/typescript-definitions/src/generated/server-api.ts (see note below)

npm run build passes.

Note on the generated files

graphics-manifest.ts is the output of npm run generate-types, unmodified.

For server-api.ts I applied the description line by hand rather than committing the
output of npm run generate-server-types. Running that regenerator against the
current toolchain produces unrelated changes: action-2 is collapsed into action,
the duplicate action-2 schema block is dropped, and an @example block appears on
one description. That suggests the committed file was generated with a different
openapi-typescript version than a fresh npm install resolves today, since the
dependency is a caret range. Rolling that drift into a one line documentation fix
seemed wrong, but it may be worth a separate look.

The `schema` field in the Graphic Manifest is described as defining the
data parameters of the 'update' method. That description omits load(),
which takes a `data` argument following the same schema, and it names a
method that does not exist, presumably meaning updateAction().

graphics-manifest.ts is a plain regeneration. The server-api.ts line was
applied by hand, because a full regeneration against the current toolchain
also produces unrelated changes.
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.

1 participant