{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uwmd.org/schemas/module-manifest.schema.json",
  "title": "UW Markdown Module Manifest",
  "description": "Declarative third-party module manifest. Normative Protocol \u00a7X; no executable code. A manifest states the host it needs with requires_conformance and optional requires_profiles; any other key is refused. Profile declarations are arrays of unique closed-vocabulary values; malformed or duplicate profiles are PROTO-MOD-006.",
  "type": "object",
  "required": [
    "manifest_version",
    "id",
    "name",
    "version",
    "description",
    "authors",
    "license",
    "requires_protocol",
    "requires_format",
    "requires_conformance"
  ],
  "additionalProperties": false,
  "properties": {
    "manifest_version": {
      "type": "string",
      "const": "1",
      "description": "Manifest schema version; always 1."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$",
      "minLength": 3,
      "maxLength": 128,
      "description": "Stable identifier; reverse-DNS recommended, e.g. com.example.specialty."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Human-readable module name."
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
      "description": "Module semver."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "authors": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier (e.g. 'MIT', 'Apache-2.0').",
      "minLength": 1
    },
    "requires_protocol": {
      "type": "string",
      "description": "Semver range satisfied by Protocol 4.0.0. No older contract is admitted."
    },
    "requires_format": {
      "type": "string",
      "description": "Semver range satisfied by Format 3.0."
    },
    "asset_classes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "multifamily",
          "office",
          "retail",
          "industrial",
          "self_storage",
          "hospitality",
          "mixed_use",
          "senior_housing",
          "student_housing",
          "land",
          "data_center",
          "manufactured_housing"
        ]
      },
      "uniqueItems": true,
      "description": "Asset classes this module is intended for. Omit to indicate the module is class-agnostic."
    },
    "deal_stages": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "scope",
          "screening",
          "term_sheet",
          "full_underwrite",
          "credit_approval",
          "closing",
          "monitoring"
        ]
      },
      "uniqueItems": true
    },
    "sections": {
      "type": "array",
      "description": "Custom or extended section declarations: extend a standard section with additional optional fields, or add module-namespaced sections. New asset_class VALUES are declared separately, in `declares_asset_classes` (RFC 0003) \u2014 this field is about sections.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "display_name",
          "schema"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "display_name": {
            "type": "string",
            "minLength": 1
          },
          "schema": {
            "type": "object",
            "description": "JSON Schema fragment for the section content. Validated by the calc host on load."
          },
          "required": {
            "type": "boolean",
            "default": false,
            "description": "If true, the host treats this section as mandatory for the declared deal_stages."
          }
        }
      }
    },
    "calculations": {
      "type": "array",
      "description": "Custom calculations contributed by this module. Each is a safe-expression formula evaluated by a Tier-3 calc host.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "label",
          "formula",
          "deterministic"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "label": {
            "type": "string",
            "minLength": 1
          },
          "formula": {
            "type": "string",
            "minLength": 1,
            "description": "Safe-expression string. Grammar: arithmetic, comparison, conditional, function call only. See UW_PROTOCOL.md \u00a7VIII.1."
          },
          "unit": {
            "type": "string",
            "description": "Display unit (e.g. '%', '$', 'x'). Also selects the default round_to when round_to is omitted \u2014 see UW_PROTOCOL.md \u00a7VIII.5."
          },
          "round_to": {
            "type": "integer",
            "minimum": 0,
            "maximum": 12,
            "description": "Decimal places the reported value is quantized to, half away from zero (UW_PROTOCOL.md \u00a7VIII.5). Omit to take the normative default for `unit` ($ = 2, % = 6, x = 4, otherwise 6). This is a precision contract that receipt digests depend on, not a display hint."
          },
          "deterministic": {
            "type": "boolean",
            "description": "MUST be true in v1. Reserved for v2 stochastic calcs."
          },
          "section_roles": {
            "type": "object",
            "description": "Role preference per section id for this calculation's reads of a role-bearing variant map (UW_PROTOCOL.md \u00a7VIII.2, RFC 0066). The unique eligible block with this _role is read; with none, RFC 0040's generic order applies; with two, the read refuses CALC-RESOLVE-002. An explicit sectionVariants entry still wins. A component is never selected this way.",
            "propertyNames": {
              "pattern": "^[a-z][a-z0-9_]*$"
            },
            "additionalProperties": {
              "enum": [
                "primary",
                "senior",
                "junior",
                "summary",
                "detail"
              ]
            }
          }
        }
      }
    },
    "validations": {
      "type": "array",
      "description": "Cross-section consistency rules contributed by this module.",
      "items": {
        "type": "object",
        "required": [
          "code",
          "severity",
          "message",
          "rule"
        ],
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^[A-Z]{2,8}-[A-Z0-9-]+$",
            "description": "Module-namespaced validation code (e.g. 'CC-MOD-HOSP-01')."
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              "info"
            ]
          },
          "message": {
            "type": "string",
            "minLength": 1
          },
          "rule": {
            "type": "string",
            "minLength": 1,
            "description": "Safe-expression returning boolean. true = passes; false = emits the message."
          }
        }
      }
    },
    "thresholds": {
      "type": "object",
      "description": "Partial override of FinancialThresholds defaults. Only properties present are overridden.",
      "additionalProperties": true
    },
    "view_models": {
      "type": "array",
      "description": "Per-section view-model overrides. Replaces BUILTIN_VIEW_MODELS entries for matching section_id.",
      "items": {
        "type": "object",
        "required": [
          "section_id",
          "display_name",
          "display_order",
          "description",
          "primary_fields"
        ],
        "additionalProperties": false,
        "properties": {
          "section_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "display_order": {
            "type": "integer",
            "minimum": 0
          },
          "description": {
            "type": "string"
          },
          "primary_fields": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/fieldViewHint"
            }
          },
          "detail_fields": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/fieldViewHint"
            }
          },
          "multi_variant": {
            "type": "boolean"
          }
        }
      }
    },
    "ui": {
      "type": "object",
      "description": "Free-form host-specific UI hints. Hosts MAY ignore unrecognized keys.",
      "additionalProperties": true
    },
    "depends_on": {
      "type": "array",
      "description": "Other modules this one requires. The host MUST refuse to load if a dependency is missing or version-incompatible.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "version"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "version": {
            "type": "string",
            "description": "Semver range."
          }
        }
      }
    },
    "declares_asset_classes": {
      "type": "array",
      "description": "Optional. Custom asset classes this module introduces (\u00a7X.2, RFC 0003). Distinct from `asset_classes`, which names builtin classes the module ENHANCES; a module may do both.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "display_name"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*([.][a-z][a-z0-9_]*){2,}$",
            "description": "Reverse-DNS, at least three lower-snake-case segments. Ownership is fixed at the identifier, so two hosts can never disagree about whose class this is. A final segment matching a builtin name is refused (INVALID-ASSET-CLASS-002)."
          },
          "display_name": {
            "type": "string",
            "minLength": 1
          },
          "fallback": {
            "enum": [
              "multifamily",
              "office",
              "retail",
              "industrial",
              "self_storage",
              "hospitality",
              "mixed_use",
              "senior_housing",
              "student_housing",
              "land",
              "data_center",
              "manufactured_housing"
            ],
            "description": "The closest builtin, for readers that do not hold this module. Omitting it is a deliberate choice that no approximation is honest, and costs those readers the document entirely (MOD-MISSING-001 rather than MOD-FALLBACK-001)."
          },
          "required_sections": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "optional_sections": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      }
    },
    "signature": {
      "$ref": "https://uwmd.org/schemas/module-signature.schema.json",
      "description": "Optional. Detached signature over the canonical manifest (\u00a7X.1, RFC 0002). Advisory: what to do with an unsigned module, or one whose signature fails, is a host-policy decision."
    },
    "requires_conformance": {
      "enum": [
        "reader",
        "verifier"
      ],
      "description": "Minimum claimed conformance tier (Protocol \u00a7VII.4). Below it is PROTO-MOD-029; unknown value is PROTO-MOD-006."
    },
    "requires_profiles": {
      "type": "array",
      "items": {
        "enum": [
          "module",
          "integrity",
          "representations",
          "portfolio",
          "sensitivity",
          "stochastic",
          "pro-forma",
          "document-facts"
        ]
      },
      "uniqueItems": true,
      "description": "Every listed profile must be claimed by the host (PROTO-MOD-029); absent means none. Unknown profiles are PROTO-MOD-006."
    }
  },
  "$defs": {
    "fieldViewHint": {
      "type": "object",
      "required": [
        "path",
        "label",
        "kind"
      ],
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string",
          "description": "Dot-path within the section's content, resolved via parser.deepGet."
        },
        "label": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "currency",
            "percent",
            "ratio",
            "count",
            "date",
            "string",
            "enum",
            "list"
          ]
        },
        "primary": {
          "type": "boolean"
        },
        "unit": {
          "type": "string"
        },
        "decimals": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10
        },
        "enum": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}
