Architecture specification

Profiles

MatJSON is a family of related profiles rather than one monolithic document. MatSpec captures intrinsic material-specification requirements. MatReq captures application overlays. MatRecord and MatCheck will normalize evidence and compliance outcomes. MatJSON Core will host shared semantics.

Profile	Primary question	Status
MatSpec	What does the material specification intrinsically require?	Working draft
MatReq	What additional requirements does another governing document impose?	Working draft
MatRecord	What evidence was actually reported?	TBC
MatCheck	What passed, failed, is missing, or needs review?	TBC

Effective requirements stack

MatSpecJSON
    + invoked MatReqJSON documents
    + direct material requisition requirements
    = effective material requirements

The material requisition remains the project-specific source of truth. MatJSON does not currently define a separate MatCtx profile.

Invocation

A requisition can invoke an entire standard, a section, a clause, an annex, or a direct purchaser-defined requirement. Informative or example content can be contractually elevated when the purchaser explicitly invokes it using mandatory language.

Material shall meet NACE MR0175.
Material shall meet API TR 938-C Appendix A.
Carbon steel shall comply with API 663 Section 8.2.
Maximum carbon equivalent shall be 0.43.

Reference-only language such as “see” or “for guidance” must not silently import an entire document.

Versioning

MatJSON separates the profile/schema version from the edition of the source engineering document. These are independent dimensions.

{
  "matjson": { "profile": "matreq", "version": "0.2" },
  "document": {
    "organization": "Example",
    "designation": "SMR-10",
    "edition": { "publication": "2026-08" }
  }
}

Canonical identifiers

Stable URIs should identify documents, grades, rules, calculations, and controlled terms. The URI can resolve to public metadata without reproducing copyrighted source text.

https://matjson.org/id/document/api/663/2022
https://matjson.org/id/rule/api/663/2022/8.2.2

Conformance

Syntactically conforming
Semantically conforming
Source-complete
Technically reviewed
Verified publication

JSON Schema validation establishes only the first level.

Extensions

Domain-specific extensions should use URI namespaces. A reader should preserve unknown extensions but must not infer that they alter core requirements.

{
  "extensions": {
    "https://example-aircraft.org/matjson": {
      "fatigue_classification": "A3"
    }
  }
}

Publication boundary

Public schemas are not the same as public standards-derived data. MatJSON schemas, tools, specifications, and synthetic examples can be published as original project work. Complete rule libraries derived from proprietary standards may require publisher authorization or controlled access.