JSON Schema
This page shows the published JSON Schema as one formatted document. Use the chevrons to fold objects and arrays, follow highlighted objects and $ref values within the schema, and use the book icons to open definition guides. You can also open the raw schema file.
{ "$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://matjson.org/schema/matreq/0.2/schema.json",
"title": "MatReqJSON Schema v0.2",
"description": "Schema for machine-readable material-related requirements imposed by codes, standards, recommended practices, technical reports, purchaser specifications, and similar governing documents. MatReqJSON supplements base MatSpecJSON and is activated by requirements or references contained in a material requisition or other contract document. Version 0.2 adds structured test/sampling fields, service-envelope and qualification rules, richer evidence/checkability, multi-source provenance, and extraction coverage.",
"type": "object",
"additionalProperties": false,
"required": [ "schema_version",
"document",
"invocation_model",
"scope",
"rules",
"provenance" ],
"properties": { "schema_version": { "const": "0.2" },
"document": { "$ref": "#/$defs/document" },
"invocation_model": { "$ref": "#/$defs/invocation_model" },
"scope": { "$ref": "#/$defs/document_scope" },
"references": { "type": "array",
"items": { "$ref": "#/$defs/document_reference" } },
"requisition_interface": { "type": "array",
"description": "Inputs or decisions that the governing document requires the purchaser/material requisition to provide. These are not project values; they define what the requisition must resolve when the associated rule is active.",
"items": { "$ref": "#/$defs/requisition_input" } },
"rules": { "type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/rule" } },
"provenance": { "$ref": "#/$defs/provenance" },
"notes": { "type": "array",
"items": { "type": "string" } },
"extensions": { "type": "object",
"additionalProperties": true,
"propertyNames": { "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
"description": "Direct extension namespace keys use lowercase snake_case." },
"description": "Extension namespaces and implementation-specific metadata. Direct MatJSON-controlled keys use lowercase snake_case." },
"coverage": { "$ref": "#/$defs/coverage" } },
"$defs": { "document": { "type": "object",
"additionalProperties": false,
"required": [ "organization",
"designation",
"document_type",
"title",
"edition" ],
"properties": { "organization": { "type": "string" },
"designation": { "type": "string",
"description": "Canonical designation, e.g. API 663, API RP 934-A, API TR 938-C, NACE MR0175/ISO 15156, ASME BPVC Section VIII Division 1." },
"aliases": { "type": "array",
"description": "Common designations that may appear in material requisitions and special material requirements. Used for reference resolution, not as separate standards.",
"items": { "type": "string" },
"uniqueItems": true },
"document_type": { "enum": [ "code",
"standard",
"specification",
"recommended_practice",
"technical_report",
"service_standard",
"purchaser_specification",
"regulation",
"other" ] },
"title": { "type": "string" },
"edition": { "$ref": "#/$defs/edition" } } },
"edition": { "type": "object",
"additionalProperties": false,
"required": [ "publication" ],
"properties": { "number": { "oneOf": [ { "type": "integer" },
{ "type": "string" } ] },
"publication": { "type": "string",
"description": "Publication date or edition year, preferably YYYY or YYYY-MM." },
"addenda": { "type": "array",
"items": { "type": "object",
"additionalProperties": false,
"required": [ "publication" ],
"properties": { "number": { "oneOf": [ { "type": "integer" },
{ "type": "string" } ] },
"publication": { "type": "string" } } } },
"reaffirmed": { "type": [ "string",
"null" ] },
"errata": { "type": "array",
"items": { "type": "object",
"additionalProperties": false,
"required": [ "publication" ],
"properties": { "number": { "oneOf": [ { "type": "integer" },
{ "type": "string" } ] },
"publication": { "type": "string" } } } },
"other_revisions": { "type": "array",
"items": { "type": "string" } } } },
"invocation_model": { "type": "object",
"additionalProperties": false,
"required": [ "accepted_sources",
"document_reference",
"scoped_reference",
"direct_rule_reference",
"contractual_reference_strength",
"cross_reference_policy" ],
"properties": { "accepted_sources": { "type": "array",
"description": "Documents from which an invocation may be established. The material requisition remains the project-specific source of truth; these fields merely identify the documents that may contain the same requisition requirements.",
"items": { "enum": [ "material_requisition",
"special_material_requirements",
"purchase_specification",
"material_datasheet",
"purchase_order",
"other_contract_document" ] },
"uniqueItems": true },
"document_reference": { "type": "object",
"additionalProperties": false,
"required": [ "behavior" ],
"properties": { "behavior": { "const": "activate_all_applicable_rules" },
"description": { "type": "string" } } },
"scoped_reference": { "type": "object",
"additionalProperties": false,
"required": [ "supported_scopes",
"behavior" ],
"properties": { "supported_scopes": { "type": "array",
"items": { "enum": [ "part",
"section",
"subsection",
"clause",
"appendix",
"annex",
"table",
"figure" ] },
"uniqueItems": true },
"behavior": { "const": "activate_rules_in_referenced_scope_and_required_dependencies" },
"description": { "type": "string" } } },
"direct_rule_reference": { "type": "object",
"additionalProperties": false,
"required": [ "behavior" ],
"properties": { "behavior": { "const": "activate_referenced_rule_and_required_dependencies" },
"description": { "type": "string" } } },
"contractual_reference_strength": { "type": "object",
"additionalProperties": false,
"required": [ "mandatory_compliance",
"reference_only" ],
"properties": { "mandatory_compliance": { "type": "object",
"additionalProperties": false,
"required": [ "behavior" ],
"properties": { "behavior": { "const": "treat_invoked_scope_as_contract_requirement" },
"examples": { "type": "array",
"items": { "type": "string" } } } },
"reference_only": { "type": "object",
"additionalProperties": false,
"required": [ "behavior" ],
"properties": { "behavior": { "const": "do_not_activate_without_additional_mandatory_language" },
"examples": { "type": "array",
"items": { "type": "string" } } } } },
"description": "A material requisition may elevate an otherwise informative/example source scope into a binding contractual requirement when it explicitly requires compliance, e.g. 'Material shall meet API TR 938-C Appendix A'. Merely saying 'refer to' or 'see' does not by itself create the same obligation." },
"cross_reference_policy": { "type": "object",
"additionalProperties": false,
"required": [ "default" ],
"properties": { "default": { "const": "explicit_effect_only" },
"description": { "type": "string",
"description": "A citation to another standard does not automatically load that standard's full MatReq. Each cross-reference must state its effect, such as full compliance, scoped compliance, test method only, definition only, or informative guidance." } } } } },
"document_scope": { "type": "object",
"additionalProperties": false,
"properties": { "equipment": { "type": "array",
"items": { "type": "string" } },
"industries": { "type": "array",
"items": { "type": "string" } },
"services": { "type": "array",
"items": { "type": "string" } },
"material_families": { "type": "array",
"items": { "type": "string" } },
"product_forms": { "type": "array",
"items": { "type": "string" } },
"description": { "type": "string" },
"included_sections": { "type": "array",
"items": { "type": "string" } },
"excluded_topics": { "type": "array",
"items": { "type": "string" } } } },
"rule": { "type": "object",
"additionalProperties": false,
"required": [ "id",
"category",
"normativity",
"targets",
"activation",
"requirement",
"verification",
"source" ],
"properties": { "id": { "type": "string",
"pattern": "^[A-Za-z0-9._:-]+$" },
"title": { "type": "string" },
"category": { "enum": [ "material_selection",
"product_form",
"chemistry",
"mechanical",
"impact",
"hardness",
"metallurgy",
"corrosion_testing",
"heat_treatment",
"manufacturing",
"welding_consumable",
"fabrication",
"nde",
"pmi",
"documentation",
"traceability",
"marking",
"dimensions",
"external_standard",
"other" ] },
"normativity": { "$ref": "#/$defs/normativity" },
"targets": { "$ref": "#/$defs/targets" },
"activation": { "$ref": "#/$defs/activation" },
"requirement": { "$ref": "#/$defs/requirement" },
"effect": { "$ref": "#/$defs/effect" },
"verification": { "$ref": "#/$defs/verification" },
"dependencies": { "$ref": "#/$defs/dependencies" },
"references": { "type": "array",
"items": { "$ref": "#/$defs/document_reference" } },
"source": { "$ref": "#/$defs/source_ref" },
"notes": { "type": "array",
"items": { "type": "string" } },
"group_id": { "type": "string" },
"structured_level": { "enum": [ "fully_structured",
"partially_structured",
"text_preserved",
"lookup_required" ] },
"sources": { "type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/source_ref" } },
"extensions": { "type": "object",
"additionalProperties": true,
"propertyNames": { "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
"description": "Direct rule-extension keys use lowercase snake_case." } } } },
"normativity": { "type": "object",
"additionalProperties": false,
"required": [ "source_level" ],
"properties": { "source_level": { "enum": [ "mandatory",
"recommended",
"permitted",
"prohibited",
"informative",
"example" ] },
"source_modal": { "enum": [ "shall",
"should",
"may",
"can",
"must",
"prohibited",
"none",
"other" ] },
"contractual_elevation_allowed": { "type": "boolean",
"description": "True when explicit mandatory invocation in the material requisition can make an informative/example source scope contractually binding." } } },
"targets": { "type": "object",
"additionalProperties": false,
"properties": { "material": { "type": "object",
"additionalProperties": false,
"properties": { "families": { "type": "array",
"items": { "type": "string" } },
"specifications": { "type": "array",
"items": { "type": "string" } },
"grades": { "type": "array",
"items": { "type": "string" } },
"uns": { "type": "array",
"items": { "type": "string" } } } },
"product_forms": { "type": "array",
"items": { "type": "string" } },
"components": { "type": "array",
"items": { "type": "string" } },
"regions": { "type": "array",
"items": { "type": "string" } },
"pressure_retaining": { "type": "boolean" },
"process_wetted": { "type": "boolean" },
"joint_types": { "type": "array",
"items": { "type": "string" } },
"weld_processes": { "type": "array",
"items": { "type": "string" } },
"services": { "type": "array",
"items": { "type": "string" } },
"service_sides": { "type": "array",
"items": { "type": "string" } },
"conditions": { "type": "array",
"items": { "type": "string" } } } },
"activation": { "type": "object",
"additionalProperties": false,
"required": [ "basis" ],
"properties": { "basis": { "enum": [ "when_document_invoked",
"when_rule_scope_invoked",
"when_condition_met",
"when_document_invoked_and_condition_met",
"when_scope_invoked_and_condition_met",
"when_explicitly_invoked_only" ] },
"when": { "$ref": "#/$defs/condition_expr" },
"requisition_input_ids": { "type": "array",
"description": "IDs from requisition_interface that must be resolved by the material requisition when this rule is active.",
"items": { "type": "string" },
"uniqueItems": true },
"notes": { "type": "array",
"items": { "type": "string" } } } },
"condition_expr": { "oneOf": [ { "$ref": "#/$defs/condition_leaf" },
{ "type": "object",
"additionalProperties": false,
"required": [ "all" ],
"properties": { "all": { "type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/condition_expr" } } } },
{ "type": "object",
"additionalProperties": false,
"required": [ "any" ],
"properties": { "any": { "type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/condition_expr" } } } },
{ "type": "object",
"additionalProperties": false,
"required": [ "not" ],
"properties": { "not": { "$ref": "#/$defs/condition_expr" } } } ] },
"condition_leaf": { "type": "object",
"additionalProperties": false,
"required": [ "field",
"op" ],
"properties": { "field": { "type": "string",
"pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*(?:\\.[a-z][a-z0-9]*(?:_[a-z0-9]+)*)*$",
"description": "Internal condition field path in lowercase snake_case." },
"op": { "enum": [ "eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"not_in",
"exists",
"contains" ] },
"value": {},
"unit": { "type": "string" } } },
"requirement": { "type": "object",
"required": [ "kind" ],
"properties": { "kind": { "enum": [ "property_limit",
"composition_limit",
"computed_limit",
"required_condition",
"required_test",
"required_examination",
"required_heat_treatment",
"required_product_form",
"required_manufacturing_route",
"required_document",
"required_report_field",
"required_traceability",
"required_marking",
"prohibited",
"allowed_only",
"relationship_constraint",
"reference_compliance",
"purchaser_defined",
"decision_procedure",
"other",
"service_limit",
"required_qualification",
"required_procedure",
"sampling_requirement",
"test_acceptance",
"required_reporting",
"figure_lookup",
"table_lookup",
"material_compatibility",
"design_property_restriction" ] },
"property": { "type": "string" },
"operator": { "enum": [ "eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"between",
"in",
"not_in" ] },
"value": {},
"minimum": {},
"maximum": {},
"unit": { "type": "string" },
"values": { "type": "array" },
"text": { "type": "string" },
"document": { "type": "string" },
"fields": { "type": "array",
"items": { "type": "string" } },
"calculation": { "$ref": "#/$defs/calculation" },
"value_from_requisition": { "type": "string",
"description": "ID of the purchaser/project value that must be obtained from the material requisition; does not store the project value in the MatReq." },
"referenced_standard": { "$ref": "#/$defs/reference_target" },
"method": { "type": [ "string",
"object" ] },
"frequency": { "type": [ "string",
"object" ] },
"sampling": { "type": [ "string",
"object",
"array" ] },
"acceptance_criteria": {},
"procedure": { "type": [ "string",
"object",
"array" ] },
"timing": { "type": [ "string",
"object" ] },
"location": { "type": [ "string",
"object",
"array" ] },
"scope": { "type": [ "string",
"object",
"array" ] },
"reporting": { "type": [ "string",
"object",
"array" ] },
"specimen": { "type": [ "string",
"object",
"array" ] },
"alternatives": { "type": "array" },
"lookup": { "type": "object" },
"basis": { "type": [ "string",
"object" ] },
"subject": { "type": [ "string",
"array" ] } },
"additionalProperties": false },
"calculation": { "type": "object",
"additionalProperties": false,
"required": [ "id",
"expression",
"inputs" ],
"properties": { "id": { "type": "string" },
"expression": { "type": "string" },
"inputs": { "type": "array",
"items": { "type": "string" } },
"result_unit": { "type": "string" },
"source": { "$ref": "#/$defs/source_ref" } } },
"effect": { "type": "object",
"additionalProperties": false,
"required": [ "relationship" ],
"properties": { "relationship": { "enum": [ "supplements",
"restricts",
"replaces",
"requires_additional_test",
"requires_additional_reporting",
"invokes",
"prohibits",
"selects",
"purchaser_defined",
"relationship_constraint" ] },
"base_requirement": { "type": "object",
"additionalProperties": false,
"properties": { "matspec": { "type": "string" },
"grade": { "type": "string" },
"path": { "type": "string" } } },
"conflict_resolution": { "enum": [ "supplement",
"explicit_override",
"most_stringent",
"source_precedence",
"project_selection",
"no_automatic_resolution" ] } } },
"verification": { "type": "object",
"additionalProperties": false,
"required": [ "evidence",
"mode" ],
"properties": { "evidence": { "type": "array",
"items": { "type": "string" },
"uniqueItems": true,
"description": "Evidence artifact types. Core values include MTR, CMTR, COC, PMI_report, NDE_report, hardness_report, impact_report, corrosion_test_report, metallurgical_test_report, ferrite_report, heat_treatment_chart, hydrotest_report, PQR, WPS, production_test_plate_report, traceability_record, inspection_record, material_requisition, and design_calculation." },
"mode": { "enum": [ "direct",
"computed",
"inspection_record",
"record_review",
"cross_document",
"manual_review" ] },
"result_if_missing": { "enum": [ "missing_evidence",
"needs_requisition_input",
"manual_review_required",
"unverified" ] },
"notes": { "type": "array",
"items": { "type": "string" } },
"checkability": { "enum": [ "mtr_direct",
"mtr_computed",
"mtr_statement",
"supporting_report",
"requisition_completeness",
"design_or_service_evaluation",
"cross_document",
"manual_only" ] },
"evidence_fields": { "type": "array",
"items": { "type": "string" } } } },
"dependencies": { "type": "object",
"additionalProperties": false,
"properties": { "requires_rule_ids": { "type": "array",
"items": { "type": "string" },
"uniqueItems": true },
"activates_rule_ids": { "type": "array",
"items": { "type": "string" },
"uniqueItems": true } } },
"reference_target": { "type": "object",
"additionalProperties": false,
"required": [ "designation" ],
"properties": { "designation": { "type": "string" },
"edition": { "type": [ "string",
"null" ] },
"scope_type": { "enum": [ "document",
"part",
"section",
"subsection",
"clause",
"appendix",
"annex",
"table",
"figure" ] },
"scope_id": { "type": "string" } } },
"document_reference": { "type": "object",
"additionalProperties": false,
"required": [ "target",
"effect" ],
"properties": { "target": { "$ref": "#/$defs/reference_target" },
"effect": { "enum": [ "invokes_all_applicable",
"invokes_scoped",
"test_method_only",
"acceptance_criteria_only",
"definition_only",
"guidance_only",
"informative_only" ] },
"activation_when": { "$ref": "#/$defs/condition_expr" },
"source": { "$ref": "#/$defs/source_ref" },
"notes": { "type": "array",
"items": { "type": "string" } } } },
"requisition_input": { "type": "object",
"additionalProperties": false,
"required": [ "id",
"type",
"source" ],
"properties": { "id": { "type": "string",
"pattern": "^[A-Za-z0-9._:-]+$" },
"description": { "type": "string" },
"type": { "enum": [ "boolean",
"number",
"string",
"selection",
"acceptance_limit",
"standard_invocation",
"scope_invocation" ] },
"unit": { "type": "string" },
"required_when": { "$ref": "#/$defs/condition_expr" },
"allowed_values": { "type": "array" },
"source": { "$ref": "#/$defs/source_ref" } } },
"source_ref": { "type": "object",
"additionalProperties": false,
"required": [ "clause" ],
"properties": { "clause": { "type": "string" },
"section_path": { "type": "array",
"description": "Hierarchical path used for scoped invocation matching, e.g. ['Annex A', 'A.2 Tubing', 'A.2.1'].",
"items": { "type": "string" } },
"page": { "oneOf": [ { "type": "integer" },
{ "type": "string" } ] },
"table": { "type": "string" },
"figure": { "type": "string" },
"text_type": { "enum": [ "normative",
"informative",
"example",
"note",
"annex",
"appendix",
"table",
"figure",
"other",
"mandatory_appendix",
"nonmandatory_appendix",
"normative_annex",
"informative_annex" ] },
"notes": { "type": "array",
"items": { "type": "string" } } } },
"provenance": { "type": "object",
"additionalProperties": false,
"required": [ "source",
"extraction_method" ],
"properties": { "source": { "type": "string" },
"extracted_on": { "type": "string" },
"extraction_method": { "enum": [ "manual",
"assisted",
"automated",
"mixed" ] },
"review_status": { "enum": [ "draft",
"reviewed",
"validated" ] },
"review_notes": { "type": "array",
"items": { "type": "string" } },
"coverage": { "enum": [ "full_material_scope",
"targeted_material_scope",
"partial_draft" ] },
"rules_generated": { "type": "integer",
"minimum": 0 },
"unresolved_items": { "type": "array",
"items": { "type": "string" } },
"source_file": { "type": "string" } } },
"coverage": { "type": "object",
"additionalProperties": false,
"required": [ "material_scope_status" ],
"properties": { "material_scope_status": { "enum": [ "full",
"targeted",
"partial" ] },
"included": { "type": "array",
"items": { "type": "string" } },
"excluded": { "type": "array",
"items": { "type": "string" } },
"lookup_required": { "type": "array",
"items": { "type": "string" } },
"limitations": { "type": "array",
"items": { "type": "string" } } } } },
"x_matjson_profile": "matreq",
"x_matjson_status": "working_draft",
"x_matjson_naming_convention": "snake_case"}