{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ramen-schema.org/ramen/1.0.0/project.schema.json",
  "title": "RAMEN project model",
  "type": "object",
  "required": ["$schema", "$id", "id", "version", "kind", "name", "imports", "classifiers", "relations", "annotations"],
  "additionalProperties": false,
  "properties": {
    "$schema": { "const": "https://ramen-schema.org/ramen/1.0.0/project.schema.json" },
    "$id": { "type": "string", "format": "uri" },
    "id": {
      "$ref": "#/$defs/Id",
      "$comment": "Stable model identifier used for imports and versioning (independent of JSON Schema $id)."
    },
    "version": { "$ref": "#/$defs/Version" },
    "kind": { "const": "Model" },
    "name": { "type": "string", "minLength": 1, "$comment": "Human-readable name of the model." },
    "imports": {
      "type": "array",
      "items": { "$ref": "#/$defs/Import" },
      "default": [],
      "$comment": "Imported models whose elements may be referenced via qualified ids."
    },
    "classifiers": {
      "type": "array",
      "items": { "$ref": "#/$defs/Classifier" },
      "default": [],
      "$comment": "Declared classifiers (node and datatype definitions)."
    },
    "relations": {
      "type": "array",
      "items": { "$ref": "#/$defs/Relation" },
      "default": [],
      "$comment": "Declared relation types between node types."
    },
    "ext": {
      "type": "object",
      "additionalProperties": true,
      "default": {},
      "description": "Opaque tool metadata. It does not change RMF model semantics and consumers may ignore it.",
      "properties": { "ramen": false }
    },
    "description": { "$ref": "#/$defs/Description" },
    "annotations": { "type": "array", "items": { "$ref": "#/$defs/RamenAnnotationShape" }, "default": [] }
  },
  "$comment": "RAMEN model format: JSON-first structural metamodel inspired by MOF/Ecore, focused on data modelling rather than full behavioural or reflective semantics.",
  "$defs": {
    "Id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "minLength": 16,
      "$comment": "Stable local identifier (minimum length 16)."
    },
    "Version": {
      "type": "string",
      "pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-.]+)?(?:\\+[0-9A-Za-z-.]+)?$",
      "$comment": "Semantic version string (MAJOR.MINOR.PATCH)."
    },
    "BuiltinType": {
      "type": "string",
      "enum": ["String", "Boolean", "Integer", "Float", "Object"],
      "$comment": "Built-in JSON value types. Object excludes arrays and null."
    },
    "LocalRef": { "$ref": "#/$defs/Id" },
    "QualifiedRef": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{16,}:[A-Za-z0-9_-]{16,}$",
      "$comment": "Qualified reference into an imported model: 'modelId:id'."
    },
    "Ref": {
      "oneOf": [{ "$ref": "#/$defs/LocalRef" }, { "$ref": "#/$defs/QualifiedRef" }],
      "$comment": "Reference to a local or imported element."
    },
    "TypeRef": {
      "oneOf": [{ "$ref": "#/$defs/BuiltinType" }, { "$ref": "#/$defs/Ref" }],
      "$comment": "Reference to a builtin or user-defined datatype."
    },
    "Import": {
      "type": "object",
      "required": ["modelUri", "modelId", "version"],
      "additionalProperties": false,
      "$comment": "Import declaration for another model.",
      "properties": {
        "modelUri": { "type": "string", "format": "uri" },
        "modelId": { "$ref": "#/$defs/Id" },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Optional display label for the import; model identity and resolution use modelId, modelUri, and version."
        },
        "version": { "$ref": "#/$defs/Version", "$comment": "Exact imported model version required for reproducible resolution." }
      }
    },
    "Bounds": {
      "type": "object",
      "required": ["lowerBound", "upperBound"],
      "additionalProperties": false,
      "$comment": "Multiplicity bounds.",
      "properties": {
        "lowerBound": { "type": "integer", "minimum": 0, "$comment": "Minimum cardinality." },
        "upperBound": { "type": "integer", "minimum": -1, "$comment": "Maximum cardinality (-1 means unbounded)." }
      }
    },
    "Constraint": {
      "description": "A rule declared in the model and evaluated against captured data. Model well-formedness is checked separately by model validation.",
      "type": "object",
      "required": ["id", "name", "language", "expression"],
      "additionalProperties": false,
      "$comment": "Declarative semantic constraint evaluated by tools.",
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "name": { "type": "string" },
        "language": { "type": "string" },
        "expression": { "oneOf": [{ "type": "string" }, { "type": "object" }] },
        "severity": { "type": "string", "enum": ["error", "warn", "info"], "default": "error" },
        "message": { "type": "string" },
        "code": { "type": "string" },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this constraint; it has no RMF validation semantics.",
          "default": {}
        },
        "description": { "$ref": "#/$defs/Description" }
      }
    },
    "Classifier": { "oneOf": [{ "$ref": "#/$defs/Node" }, { "$ref": "#/$defs/DataType" }] },
    "Node": {
      "type": "object",
      "required": ["kind", "id", "name", "superTypes", "attributes"],
      "additionalProperties": false,
      "$comment": "Node type (class) declaration.",
      "properties": {
        "kind": { "const": "Node" },
        "id": { "$ref": "#/$defs/Id" },
        "name": { "type": "string" },
        "superTypes": {
          "description": "The node refined by this declaration. Models with imports must declare exactly one base node; only models without imports may declare nodes without a base. Existing imported nodes can be reused without a local declaration. The model validator checks this contextual rule.",
          "type": "array",
          "items": { "$ref": "#/$defs/Ref" },
          "default": [],
          "maxItems": 1
        },
        "attributes": { "type": "array", "items": { "$ref": "#/$defs/Attribute" }, "default": [] },
        "constraints": { "type": "array", "items": { "$ref": "#/$defs/Constraint" }, "default": [] },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this node; it has no RMF model semantics.",
          "default": {}
        },
        "description": { "$ref": "#/$defs/Description" }
      }
    },
    "DataType": {
      "type": "object",
      "required": ["kind", "id", "name", "baseType"],
      "additionalProperties": false,
      "$comment": "User-defined datatype with a JSON-compatible representation; scalar literals make the value domain an enumeration.",
      "properties": {
        "kind": { "const": "DataType" },
        "id": { "$ref": "#/$defs/Id" },
        "name": { "type": "string" },
        "baseType": {
          "$ref": "#/$defs/BuiltinType",
          "$comment": "Value representation validated before datatype literals and constraints."
        },
        "literals": {
          "description": "A non-empty enumeration. String literals use literal exactly as written, or name when literal is absent. Numeric literals require value. Boolean enumerations are not supported; use the Boolean primitive instead.",
          "type": "array",
          "items": { "$ref": "#/$defs/Literal" },
          "minItems": 1
        },
        "constraints": { "type": "array", "items": { "$ref": "#/$defs/Constraint" }, "default": [] },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this data type; it has no RMF model semantics.",
          "default": {}
        },
        "description": { "$ref": "#/$defs/Description" }
      }
    },
    "Literal": {
      "type": "object",
      "required": ["id", "name"],
      "additionalProperties": false,
      "$comment": "Enumeration literal.",
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "name": { "type": "string" },
        "value": {
          "type": "number",
          "description": "Numeric value represented by this literal. Integer data types require a whole number; Float data types also allow fractions."
        },
        "literal": {
          "type": "string",
          "description": "String value represented by this literal; name remains its display label."
        },
        "constraints": { "type": "array", "items": { "$ref": "#/$defs/Constraint" }, "default": [] },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this literal; it has no RMF model semantics.",
          "default": {}
        },
        "description": { "$ref": "#/$defs/Description" }
      }
    },
    "Attribute": {
      "type": "object",
      "required": ["id", "name", "typeId", "bounds"],
      "additionalProperties": false,
      "$comment": "Structural attribute (property) of a node type.",
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "name": { "type": "string" },
        "typeId": { "$ref": "#/$defs/TypeRef" },
        "bounds": { "$ref": "#/$defs/Bounds" },
        "isKey": {
          "type": "boolean",
          "default": false,
          "description": "Marks the sole key of this node type, including inherited attributes. Requires cardinality 1..1. Values must be unique across records of the declaring node and all its refinements in the complete validated data graph. Independent key declarations have separate uniqueness scopes."
        },
        "isReadOnly": {
          "type": "boolean",
          "default": false,
          "description": "Tells data-entry tools that a value may be set on creation but should not be changed afterward. This rule concerns edits over time, not one data snapshot."
        },
        "isOrdered": {
          "type": "boolean",
          "default": true,
          "description": "For a multi-valued attribute, array position carries domain meaning when true. The current validator does not impose a canonical order."
        },
        "isUnique": {
          "type": "boolean",
          "default": true,
          "description": "For one data record, a multi-valued attribute must not contain duplicate values when true. This is distinct from key uniqueness across records."
        },
        "constraints": { "type": "array", "items": { "$ref": "#/$defs/Constraint" }, "default": [] },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this attribute; it has no RMF model semantics.",
          "default": {}
        },
        "description": { "$ref": "#/$defs/Description" }
      }
    },
    "Relation": {
      "type": "object",
      "required": ["kind", "id", "superTypes", "name", "from", "to"],
      "additionalProperties": false,
      "$comment": "Relation type connecting node types.",
      "properties": {
        "kind": { "const": "Relation" },
        "id": { "$ref": "#/$defs/Id" },
        "superTypes": { "type": "array", "items": { "$ref": "#/$defs/Ref" }, "default": [], "maxItems": 1 },
        "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
        "from": { "$ref": "#/$defs/RelationEnd" },
        "to": { "$ref": "#/$defs/RelationEnd" },
        "constraints": { "type": "array", "items": { "$ref": "#/$defs/Constraint" }, "default": [] },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this relation; it has no RMF model semantics.",
          "default": {}
        },
        "description": { "$ref": "#/$defs/Description" }
      }
    },
    "RelationEnd": {
      "type": "object",
      "required": ["id", "nodeId", "bounds"],
      "additionalProperties": false,
      "$comment": "Association end with node reference and cardinality.",
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "nodeId": { "$ref": "#/$defs/Ref" },
        "bounds": { "$ref": "#/$defs/Bounds" },
        "constraints": { "type": "array", "items": { "$ref": "#/$defs/Constraint" }, "default": [] },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata for this relation end; it has no RMF model semantics.",
          "default": {}
        }
      }
    },
    "Description": {
      "type": "string",
      "maxLength": 2000,
      "description": "Optional plain-text documentation of a definition. It does not constrain captured data."
    },
    "RamenId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,}$" },
    "RamenRef": { "type": "string", "pattern": "^(?:[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{16,}:[A-Za-z0-9_-]{16,})$" },
    "RamenBounds": {
      "type": "object",
      "required": ["lowerBound", "upperBound"],
      "additionalProperties": false,
      "properties": { "lowerBound": { "type": "integer", "minimum": 0 }, "upperBound": { "type": "integer", "minimum": -1 } }
    },
    "RamenAnnotationShapeProperty": {
      "description": "A property declared only for this annotation shape. Shared node properties apply automatically.",
      "$ref": "https://ramen-schema.org/model/1.0.0/schema.json#/$defs/Attribute"
    },
    "RamenAnnotationShapeRelation": {
      "type": "object",
      "description": "Selects one or more modelled relations for this annotation shape. Their matches share one cardinality interval.",
      "required": ["relationIds", "direction", "bounds"],
      "additionalProperties": false,
      "properties": {
        "relationIds": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "$ref": "#/$defs/RamenRef" },
          "description": "References to modelled relations counted together. Their endpoint types determine which nodes can be connected."
        },
        "direction": {
          "enum": ["outgoing", "incoming"],
          "description": "Direction viewed from the Annotation node. An incoming HAS_ANNOTATION relation determines a permitted carrier such as Text or Image."
        },
        "bounds": {
          "$ref": "#/$defs/RamenBounds",
          "description": "Total number of matching relations allowed for one annotation; it must not widen the modelled cardinality."
        }
      }
    },
    "RamenAnnotationShape": {
      "type": "object",
      "description": "One closed type value scoped to an Annotation node and inherited by refinements of that node.",
      "required": ["id", "annotationId", "type", "properties", "relations"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/RamenId",
          "description": "Stable identifier of this type declaration, separate from its serialised type value."
        },
        "annotationId": {
          "$ref": "#/$defs/RamenRef",
          "description": "Annotation node on which this type is declared. It may be the imported RAMEN Annotation node."
        },
        "type": {
          "type": "string",
          "minLength": 1,
          "description": "Required value of the Annotation.type property in data using this declaration."
        },
        "properties": {
          "type": "array",
          "description": "Properties owned by this type. Node properties, including inherited ones, apply automatically and cannot be redeclared here.",
          "items": { "$ref": "#/$defs/RamenAnnotationShapeProperty" },
          "default": []
        },
        "relations": {
          "type": "array",
          "description": "Complete allowlist of incoming and outgoing relations for this type. Omitted relations are not available to data using it.",
          "items": { "$ref": "#/$defs/RamenAnnotationShapeRelation" },
          "default": []
        },
        "description": { "$ref": "https://ramen-schema.org/model/1.0.0/schema.json#/$defs/Description" },
        "ext": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque tool metadata, preserved without interpretation."
        }
      }
    }
  }
}
