Repository navigation
md-models 0.3.0
This release makes generated JSON-LD a complete, valid RDF graph, adds an IRI type, makes SHACL validate what the generators produce, and fixes how defaults, patterns and names are handled. Generated output changes for every user, so read Breaking before upgrading.
Breaking
- Names keep their capitals and acronyms. To PascalCase an object, enum or type name, md-models now joins the words on spaces,
_and-and capitalizes only the first letter of each word:HTTPRequeststaysHTTPRequest(0.2.8–0.2.10 producedHttpRequest), andXML documentbecomesXMLDocument.- This renames generated classes, structs, XML elements, GraphQL types and JSON Schema files.
- It also changes class and property IRIs in OWL, SHACL, ShEx and JSON-LD.
- Type references must use the heading's capitals, and
--roottakes the new name.
- Prefixes are used verbatim. md-models no longer appends
/to front-matter prefixes.- End each IRI with its separator:
https://schema.org/,…/rdf-schema#,…/obo/CHEBI_. - A warning is printed when a prefix IRI ends in a letter or digit.
- Prefixes that do not end in
: / ? # [ ] @are emitted as{"@id": …, "@prefix": true}.
- End each IRI with its separator:
- Default
repois now the reserved placeholderhttps://example.org/<prefix>/(it washttp://mdmodel.net/).- A warning is printed on stderr when a semantic format is generated from it.
- Set
repoto a namespace you control. - If
repolacks a separator,repo#is used as the namespace.
- Defaults are kept as written.
- A quoted default is a string:
Default: "2.0"is the string2.0, no longer the float 2.0. - An unquoted default on a
stringfield is a string. - Floats keep their decimal point.
DataType::String(Rust, Python, WASM) now holds the text without quotes.- Internal-schema files written by ≤ 0.2.10 store string defaults with embedded quotes; regenerate them.
- A quoted default is a string:
- Pydantic enforces
Pattern. Single-valuedstrfields getpattern=, so data that does not match is now rejected on load.- Before, the pattern was stored with literal quotes and never matched anything.
- Example: a field with
Pattern: "^(\d+)\.\d+$"now rejects"2".
- JSON-LD contexts (Pydantic, dataclass, Rust
-O jsonld,json-ld):- every field is mapped (
<prefix>:<Object>/<field>when it has no Term), with@vocabas a fallback; Identifierfields are literals; onlyIRIfields are links;- all arrays are ordered
@lists, so empty arrays appear asrdf:nil; - pure
datefields are typedxsd:date; - there is no
@typeinside scoped contexts.
- every field is mapped (
- SHACL:
- one
sh:pathper property (the Term if set, else<Object>:<field>); - list paths for arrays; a required array needs at least one item;
- shapes for every object.
- one
- OWL:
- array and
IRIproperties are object properties withoutrdfs:range; - required arrays use
owl:minCardinality 1.
- array and
- Rust API:
- new
Attribute::is_irifield (use..Default::default()in struct literals); DataModel::json_schemaandjson_schema_allreturn errors instead of panicking;- the generated Rust JSON-LD
TermDetailhas a newprefixfield.
- new
New
Type: IRI/IRI[]for fields that hold IRIs. They become JSON-LD links, JSON Schemaformat: iri(single-valued), SHACLsh:nodeKind sh:IRI, and OWL object properties.- Pydantic models read
@id,@typeand@contextback from documents.- Extra types and prefixes survive a write and re-read, and generated term mappings take precedence.
- Compacted JSON-LD loads too: a single
@typestring, a string or list@context, or anull@id.
- SHACL validates the generated data. Shapes use the JSON-LD datatypes (float and number accept integer or double), enum values via
sh:in, and declared prefixes.
Fixes
- Python defaults: no longer broken or wrong (
""x"", or"2"for"2.0"). - Rust string defaults: now escaped.
Pattern/Example: quotes no longer leak into the output (JSON Schema, LinkML, mkdocs, markdown, Pydantic-XML, whose output did not compile).- XSD defaults: no more
default=""…"". #prefixes: no stray/after them (rdf-schema#/).- IRIs: no more glued forms like
http://mdmodel.netDoc/id. - The SHACL output parses. Before, it used undeclared prefixes and invalid
sh:orpaths. - Errors instead of panics: an unknown
--rootforjson-schema, orjson-schema-allwithout-o. - ShEx warning: printed on stderr instead of stdout.
Known limitations
- ShEx shapes do not model lists yet, so they reject array data.
- Parsing a default by its declared type requires
Typeto come beforeDefault. - Markdown and LinkML exports do not preserve
IRI. - OWL ranges for floats (
xsd:decimal) and enums (classes) do not yet match the JSON-LD data (xsd:double, string literals).
Upgrading
- Regenerate generated code and schemas with 0.3.0, and review the diff: class names with acronyms, IRIs, JSON-LD contexts, SHACL and OWL change.
- Specs:
- check that every front-matter prefix ends in its separator (md-models warns if not);
- set
repoto a namespace you control; - write type references with the same capitals as the object heading.
- Data: values that never matched their spec's
Patternare now rejected by the generated Pydantic models. - Internal-schema JSON written by ≤ 0.2.10: regenerate it, because string defaults there still carry embedded quotes.
- Python: the
mdmodelspackage needs a release that allowsmdmodels-core0.3 before it can use this version.