Skip to content

v0.3.0

Latest

Choose a tag to compare

@haeussma haeussma released this 11 Oct 15:42
· 5 commits to main since this release
b0310ea

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: HTTPRequest stays HTTPRequest (0.2.8–0.2.10 produced HttpRequest), and XML document becomes XMLDocument.
    • 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 --root takes 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}.
  • Default repo is now the reserved placeholder https://example.org/<prefix>/ (it was http://mdmodel.net/).
    • A warning is printed on stderr when a semantic format is generated from it.
    • Set repo to a namespace you control.
    • If repo lacks a separator, repo# is used as the namespace.
  • Defaults are kept as written.
    • A quoted default is a string: Default: "2.0" is the string 2.0, no longer the float 2.0.
    • An unquoted default on a string field 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.
  • Pydantic enforces Pattern. Single-valued str fields get pattern=, 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 @vocab as a fallback;
    • Identifier fields are literals; only IRI fields are links;
    • all arrays are ordered @lists, so empty arrays appear as rdf:nil;
    • pure date fields are typed xsd:date;
    • there is no @type inside scoped contexts.
  • SHACL:
    • one sh:path per property (the Term if set, else <Object>:<field>);
    • list paths for arrays; a required array needs at least one item;
    • shapes for every object.
  • OWL:
    • array and IRI properties are object properties without rdfs:range;
    • required arrays use owl:minCardinality 1.
  • Rust API:
    • new Attribute::is_iri field (use ..Default::default() in struct literals);
    • DataModel::json_schema and json_schema_all return errors instead of panicking;
    • the generated Rust JSON-LD TermDetail has a new prefix field.

New

  • Type: IRI / IRI[] for fields that hold IRIs. They become JSON-LD links, JSON Schema format: iri (single-valued), SHACL sh:nodeKind sh:IRI, and OWL object properties.
  • Pydantic models read @id, @type and @context back 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 @type string, a string or list @context, or a null @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="&quot;…&quot;".
  • # 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:or paths.
  • Errors instead of panics: an unknown --root for json-schema, or json-schema-all without -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 Type to come before Default.
  • 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 repo to a namespace you control;
    • write type references with the same capitals as the object heading.
  • Data: values that never matched their spec's Pattern are 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 mdmodels package needs a release that allows mdmodels-core 0.3 before it can use this version.