Verified against: v1.0.0-rc.1 (4cb3abc5)
Summary
Every migration guide (from-json-schema, from-rdf, from-owl-shacl, from-python,
from-legacy-osw) is written for a human authoring one schema by hand. docs/mappings.md compares
OO-LD with other formats but does not prescribe a procedure.
Nothing covers the case of a generator: a tool that mechanically emits many OO-LD schemas from an
existing model on every upstream release. That case has decisions a hand-author never faces, and
right now every project answers them differently.
Context
Converting the EU Battery Passport model (SAMM, seven modules, 141 properties) produced 40 OO-LD
schemas. Four questions came up that the specification does not answer, and each one had to be
resolved by guesswork.
The four questions
1. What if the source has no payload context?
This is the whole SAMM case and it is not a niche one. SAMM emits a file named <Aspect>-ld.json
that looks like it should be the JSON-LD context, and is not: it is the aspect model itself
serialised as a @graph of meta-model nodes, with zero payload term definitions. The context has to
be derived from the model's IRIs, not lifted from any file.
The documentation's SAMM section shows a finished context without saying where it came from, which is
exactly the step that is hard. A sentence naming the problem would have saved a day.
2. Preserve the source IRIs, or mint new ones?
SAMM identifies everything with non-dereferenceable, version-scoped URNs:
urn:samm:io.BatteryPass.Circularity:1.0.0#recycledContent
urn:samm:io.BatteryPass.Circularity:1.2.0#recycledContent
These are different predicates, so data from two model versions will not join in a graph. Preserving
them keeps traceability to the source and inherits the problem. Minting https:// IRIs fixes it and
invents a vocabulary that does not exist upstream.
This is a real modelling fork with long-term consequences, and there is no guidance on how to think
about it. A short section on when to preserve versus mint, and on carrying the source IRI as an
x-oold-context synonym when you mint, would help.
3. How do you derive a stable x-oold-uuid?
The specification says only that it is "RECOMMENDED to mint it from an autogenerated UUID". For a
generator, a random UUID is actively wrong: every regeneration produces a new one and the diff churns
on every release, which destroys the ability to review what actually changed.
This project used uuid5(NAMESPACE_URL, <class IRI>), which is deterministic and reproducible, but
that is an invention. If two generators pick different schemes, the same logical class ends up with
different UUIDs in different toolchains, which defeats the purpose of a stable identifier "across
versions and locations".
A recommended derivation for generated schemas would be worth a paragraph.
4. How do you version a generated schema?
x-oold-version here mirrors the SAMM model version (1.2.0). But fixing a converter bug changes
the emitted schema while the source model is untouched. There are two independent axes, source
version and generator version, and one field.
The versioning section assumes hand-authored schemas where the two coincide. It is not obvious
whether the intended answer is to bump x-oold-version for generator changes (which then lies about
the source), to leave it (which then lies about the schema), or to record the generator separately.
Suggested outcome
A docs/migration/from-a-generator.md, or a section in mappings.md, covering:
- deriving a context when the source has none
- preserving versus minting IRIs, and recording the source IRI either way
- a recommended deterministic
x-oold-uuid derivation
- how the two version axes map onto
x-oold-version and friends
- naming conventions for
$id filenames and title, which are also currently unspecified
A worked, CI-validated generator example would be better still, but the prose alone would remove most
of the guesswork.
Reference implementation
We have a working SAMM to OO-LD converter
that answers all four questions, documenting each answer as
a decision rather than a rule. It reaches 40/40 on Circularity and converts all seven Battery
Passport modules. It is offered as evidence of what the questions are, not as a proposal for how they
should be settled; happy to share the repository if that would help.
Verified against:
v1.0.0-rc.1(4cb3abc5)Summary
Every migration guide (
from-json-schema,from-rdf,from-owl-shacl,from-python,from-legacy-osw) is written for a human authoring one schema by hand.docs/mappings.mdcomparesOO-LD with other formats but does not prescribe a procedure.
Nothing covers the case of a generator: a tool that mechanically emits many OO-LD schemas from an
existing model on every upstream release. That case has decisions a hand-author never faces, and
right now every project answers them differently.
Context
Converting the EU Battery Passport model (SAMM, seven modules, 141 properties) produced 40 OO-LD
schemas. Four questions came up that the specification does not answer, and each one had to be
resolved by guesswork.
The four questions
1. What if the source has no payload context?
This is the whole SAMM case and it is not a niche one. SAMM emits a file named
<Aspect>-ld.jsonthat looks like it should be the JSON-LD context, and is not: it is the aspect model itself
serialised as a
@graphof meta-model nodes, with zero payload term definitions. The context has tobe derived from the model's IRIs, not lifted from any file.
The documentation's SAMM section shows a finished context without saying where it came from, which is
exactly the step that is hard. A sentence naming the problem would have saved a day.
2. Preserve the source IRIs, or mint new ones?
SAMM identifies everything with non-dereferenceable, version-scoped URNs:
These are different predicates, so data from two model versions will not join in a graph. Preserving
them keeps traceability to the source and inherits the problem. Minting
https://IRIs fixes it andinvents a vocabulary that does not exist upstream.
This is a real modelling fork with long-term consequences, and there is no guidance on how to think
about it. A short section on when to preserve versus mint, and on carrying the source IRI as an
x-oold-contextsynonym when you mint, would help.3. How do you derive a stable
x-oold-uuid?The specification says only that it is "RECOMMENDED to mint it from an autogenerated UUID". For a
generator, a random UUID is actively wrong: every regeneration produces a new one and the diff churns
on every release, which destroys the ability to review what actually changed.
This project used
uuid5(NAMESPACE_URL, <class IRI>), which is deterministic and reproducible, butthat is an invention. If two generators pick different schemes, the same logical class ends up with
different UUIDs in different toolchains, which defeats the purpose of a stable identifier "across
versions and locations".
A recommended derivation for generated schemas would be worth a paragraph.
4. How do you version a generated schema?
x-oold-versionhere mirrors the SAMM model version (1.2.0). But fixing a converter bug changesthe emitted schema while the source model is untouched. There are two independent axes, source
version and generator version, and one field.
The versioning section assumes hand-authored schemas where the two coincide. It is not obvious
whether the intended answer is to bump
x-oold-versionfor generator changes (which then lies aboutthe source), to leave it (which then lies about the schema), or to record the generator separately.
Suggested outcome
A
docs/migration/from-a-generator.md, or a section inmappings.md, covering:x-oold-uuidderivationx-oold-versionand friends$idfilenames andtitle, which are also currently unspecifiedA worked, CI-validated generator example would be better still, but the prose alone would remove most
of the guesswork.
Reference implementation
We have a working SAMM to OO-LD converter
that answers all four questions, documenting each answer as
a decision rather than a rule. It reaches 40/40 on Circularity and converts all seven Battery
Passport modules. It is offered as evidence of what the questions are, not as a proposal for how they
should be settled; happy to share the repository if that would help.