2.0.778

Full Changelog: v1.0.576...v2.0.778

Introducing COGS 2.0: More languages, clearer models, and dependable data exchange

COGS 2.0 brings your information models closer to the applications that use them. With new Python and TypeScript generators, stronger validation, and substantial improvements across schemas, ontologies, and documentation, this release helps teams carry the same model from its original definition into working software.

The foundation remains familiar: describe your model using straightforward directories, CSV files, and Markdown. Domain experts can contribute without learning a schema language, while developers generate the code and technical artifacts they need from those shared definitions. COGS 2.0 builds on that approach with a clearer contract for what models mean and how their data travels between systems.

• Python joins the supported programming languages—with a choice of dataclasses or Pydantic.
  COGS now generates typed Python 3.11+ packages, including JSON and XML serialization. Choose dependency-free dataclasses for a lightweight starting point, or generate Pydantic v2 models for applications that benefit from strict fields, assignment validation, and Pydantic’s ecosystem. Both flavors support inheritance, recursive models, and shared item references, with natural Python attribute names that preserve the original COGS names when exchanging data.

• TypeScript generation makes models easier to use in JavaScript applications.
  The new generator produces a Node 22+ ESM package with TypeScript source, build configuration, and generated JavaScript and declaration files. Classes expose familiar camelCase members, while the serializers handle COGS JSON/XML names, polymorphism, and reference identity. The supported numeric domain works with ordinary JSON.parse and JSON.stringify; the generated reader also checks incoming numeric text before parsing can hide precision problems.

• A much broader conformance suite supports the release.
  Verification now exercises generated C#, both Python flavors, and TypeScript, including round trips through the languages in both directions. Every intermediate JSON/XML document is validated, with checks for values, concrete types, ordering, and reference identity. Additional coverage includes generated-package builds, documentation, secondary artifacts, and repeatable generation. CI is configured for Windows and Linux with pinned tools, and NuGet package patch versions now come from the Git commit count.

• Generated APIs use more familiar native types.
  COGS 2.0 reduces the need for special-purpose scalar wrappers. C# models use types such as decimal, DateTimeOffset, DateOnly, TimeOnly, and TimeSpan; Python uses Decimal and the standard datetime types; TypeScript uses numbers, Date, and strings where appropriate. These mappings share explicit value limits so supported values can travel between languages reliably. Partial dates, multilingual strings, and other values with richer meaning retain structured representations.

• JSON, XML, and generated code follow a more consistent serialization contract.
  Improvements cover inheritance, abstract types, property-specific subtype permissions, recursive composites, and identities made from multiple fields. Forward and repeated references resolve to the same logical item, and external references remain distinguishable from full definitions. JSON Schema now combines inherited definitions with allOf and closes complete objects with unevaluatedProperties, allowing valid inherited properties while rejecting unexpected content. Unused composite definitions are omitted, making generated schemas easier to navigate.

• Instance validation gives teams a direct way to check real data.
  The new cogs validate-instance command validates JSON or XML against the model, combining generated-schema checks with COGS rules that schemas cannot fully express. These include numeric interchange limits, primitive value constraints, duplicate definitions, and identity rules. Model validation has also become more thorough, with clearer diagnostics for invalid settings, inheritance problems, naming conflicts, and malformed convention files. New warnings help authors spot unused composites and abstract types without concrete descendants.

• Ontology generation has been substantially rebuilt.
  OWL output now uses readable, standards-compliant Turtle. Shared properties are declared once, while restrictions and descriptions stay attached to the classes where they apply. A common naming convention aligns property IRIs across OWL, generated C# RDF, LinkML, and DCTAP: class names retain PascalCase, while predicates use word-aware camelCase. Generated C# RDF also receives corrected datatype handling, consistent identifiers, and better support for structured primitive values.

• The wider publishing ecosystem is more useful and more explicit about its limits.
  UML/XMI generation has stronger handling of inheritance, multiplicity, ordering, identification, and references. LinkML, DCTAP, and GraphQL more faithfully represent the parts of the model their formats support, including shared properties, compound identities, and subtype relationships. Publisher capability documentation now distinguishes preserved semantics from approximations and unsupported features, helping teams choose an output with a clearer understanding of what it guarantees.

• Generated documentation better reflects the model people actually wrote.
  Markdown content is processed through MyST, preserving its intended formatting within Sphinx documentation. Improvements cover type descriptions, topics, articles, navigation, and diagrams. When Graphviz is unavailable, documentation can still be generated without broken diagram references. Generated XSD documentation now explains restricted scalar domains individually and introduces the model using its title, description, version, authorship, and copyright information. The command reference is generated from the CLI itself, keeping documented options aligned with the tool.

• Publication and migration are safer.
  Directory publishers generate into staging areas and replace existing output transactionally, restoring previous output if publication fails. Canonical-path checks protect source models from overlapping output directories. The rewrite --upgrade-cogs-2 command helps with mechanical migration work, including settings, flags, cardinalities, and marker-file casing, with Git-aware handling of tracked renames. Library callers also gain structured results that retain diagnostics throughout loading, model construction, and publication.

COGS 2.0 is a major release, and some of these cross-serialization improvements require migration. The native-type profile deliberately narrows some value domains. Instance integers must fit within JavaScript’s safe-integer range and their datatype’s existing sign or size restrictions. Decimals must satisfy an exact, bounded interchange profile, and values requiring rounding are rejected. Timestamps require a timezone and normalize to UTC at millisecond precision. Dates use years 0001–9999 without offsets, local times support microseconds, and durations represent elapsed whole milliseconds without calendar years or months. Floating-point zero is canonicalized to positive zero. These choices make generated models easier to use while making interoperability expectations explicit.