{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tiffany.systems/api/schema/portal-resource.schema.json",
  "title": "PortalResource",
  "description": "The canonical input contract for anything Tiffany offers or may one day offer. One record drives the human page and the machine document, so the two cannot disagree. Every optional field means UNKNOWN when absent and stays absent until an authorised input supplies it — the renderer never writes prose to cover a gap, and the ingestion validator rejects a record that asserts availability, capability or release without the object that would justify it.",
  "x-schema-version": "1.0.0",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "name", "resource_type", "development_state", "release_status", "access", "short_description", "record"],
  "properties": {
    "id": {"type": "string", "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", "description": "Stable identity, never derived from the display name."},
    "name": {"type": "string", "description": "Canonical name as it should be printed."},
    "short_name": {"type": ["string", "null"]},
    "acronym": {"type": ["string", "null"]},
    "canonical_expansion": {"type": ["string", "null"], "description": "What the acronym stands for. Null until established and cleared. An expansion is a claim about what a thing is and is never inferred from the letters."},

    "resource_type": {"type": "string", "enum": ["SYSTEM", "MODULE", "APPLICATION", "API", "SDK", "DATASET", "EVIDENCE_DATABASE", "RESEARCH_COLLECTION", "TOOL", "LIBRARY", "INTEGRATION", "DOCUMENTATION", "SCHEMATIC", "REPRODUCIBILITY_PACKAGE", "RELEASE_ARTIFACT", "DEVELOPER_RESOURCE", "RESEARCH_PROGRAMME", "RESEARCH_OBJECTIVE", "UNDETERMINED"], "description": "UNDETERMINED is the correct value for something in discovery whose eventual form is an open question. Choosing MODULE or APPLICATION early asserts a shape the work has not settled."},

    "development_state": {"type": "string", "enum": ["DISCOVERY", "DESIGNING", "EXPERIMENTAL_INTERNAL", "REALIZATION_PENDING", "QUALIFICATION_PENDING", "PUBLICATION_REVIEW_PENDING", "PUBLICATION_CLEARED", "AVAILABLE", "LIMITED", "NOT_YET_AVAILABLE", "SUPERSEDED", "WITHDRAWN"]},
    "scientific_status": {"type": ["string", "null"], "enum": ["FROZEN_ADOPTED", "QUALIFIED", "QUALIFIED_AT_CURRENT_SCOPE", "EXPERIMENTAL", "FRONTIER_BOUNDED", "UNOBSERVED", "NOT_PRODUCTION_QUALIFIED", null], "description": "Null unless a scientific claim is actually attached and authorised. Most software has none, which is correct rather than missing."},
    "release_status": {"type": "string", "enum": ["UNRELEASED", "PREVIEW", "CURRENT", "SUPERSEDED", "WITHDRAWN"]},
    "access": {"type": "string", "enum": ["PUBLIC", "AUTHENTICATED", "RESTRICTED", "INTERNAL"], "description": "INTERNAL records are never rendered publicly. The generator refuses them rather than filtering them late."},

    "short_description": {"type": "string", "minLength": 10, "description": "One or two sentences that are true today. For a discovery-state resource this says what the work is and that details are not public — never what the thing will do."},
    "long_description": {"type": ["string", "null"]},
    "purpose": {"type": ["string", "null"]},
    "role_in_tiffany": {"type": ["string", "null"], "description": "Public-safe statement of how it fits. Null while the role is itself an open question."},

    "architecture_summary": {"type": ["string", "null"]},
    "architecture_version": {"type": ["string", "null"]},
    "architecture_cleared": {"type": ["boolean", "null"], "description": "Architecture and schematics render only when this is true. Clearance is recorded, never assumed."},

    "interfaces": {"type": ["array", "null"], "items": {"type": "object", "additionalProperties": false, "required": ["kind", "ref"], "properties": {"kind": {"type": "string", "enum": ["HTTP_API", "FILE_FORMAT", "CLI", "SCHEMA", "DOCUMENT"]}, "ref": {"type": "string"}, "note": {"type": ["string", "null"]}}}},
    "inputs": {"type": ["array", "null"], "items": {"type": "string"}},
    "outputs": {"type": ["array", "null"], "items": {"type": "string"}},
    "dependencies": {"type": ["array", "null"], "items": {"type": "string"}},

    "capabilities": {"type": ["array", "null"], "items": {"type": "string"}, "description": "Capability record ids. A capability may be listed only if an authorised capability record exists for it."},
    "limitations": {"type": ["array", "null"], "items": {"type": "string"}},
    "non_capabilities": {"type": ["array", "null"], "items": {"type": "string"}, "description": "Things it explicitly does not do. Stated so that absence of a claim is not read as a quiet claim."},
    "use_cases": {"type": ["array", "null"], "items": {"type": "string"}},

    "platforms": {"type": ["array", "null"], "items": {"type": "string"}},
    "application_state": {"type": ["string", "null"], "enum": ["NONE", "IN_DEVELOPMENT", "RELEASED", null]},
    "api_available": {"type": ["boolean", "null"], "description": "True requires at least one documented interface of kind HTTP_API."},
    "docs_available": {"type": ["boolean", "null"]},

    "evidence_links": {"type": ["array", "null"], "items": {"type": "string"}},
    "evidence_state": {"type": ["string", "null"], "enum": ["NONE_PUBLISHED", "PARTIAL", "PUBLISHED", null]},
    "qualification_scope": {"type": ["string", "null"]},
    "research_status": {"type": ["string", "null"]},
    "agi_relationship": {"type": ["string", "null"], "description": "Public-safe statement of how this relates to the AGI research objective, if at all. Never an achievement claim."},

    "schematics": {"type": ["array", "null"], "items": {"type": "string"}},
    "releases": {"type": ["array", "null"], "items": {"type": "object"}},
    "downloads": {"type": ["array", "null"], "items": {"type": "object", "additionalProperties": false, "required": ["artifact_id", "version", "platform", "sha256", "license"], "properties": {"artifact_id": {"type": "string"}, "version": {"type": "string"}, "platform": {"type": "string"}, "architecture": {"type": ["string", "null"]}, "url": {"type": ["string", "null"]}, "bytes": {"type": ["integer", "null"]}, "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "signature": {"type": ["string", "null"]}, "license": {"type": "string"}, "requirements": {"type": ["array", "null"], "items": {"type": "string"}}, "install": {"type": ["string", "null"]}, "release_notes": {"type": ["string", "null"]}, "security_notes": {"type": ["string", "null"]}, "release_status": {"type": "string", "enum": ["CURRENT", "SUPERSEDED", "DEPRECATED", "WITHDRAWN"]}}}},
    "datasets": {"type": ["array", "null"], "items": {"type": "string"}},

    "provenance": {"type": ["object", "null"], "additionalProperties": false, "properties": {"publication_decision_ref": {"type": ["string", "null"]}, "cleared_at": {"type": ["string", "null"]}, "cleared_version": {"type": ["string", "null"]}, "authority": {"type": ["string", "null"]}}},
    "supersedes": {"type": ["string", "null"]},
    "superseded_by": {"type": ["string", "null"]},
    "relationships": {"type": ["array", "null"], "items": {"type": "object", "additionalProperties": false, "required": ["type", "target"], "properties": {"type": {"type": "string", "enum": ["PART_OF", "DEPENDS_ON", "IMPLEMENTS", "EXPOSES_API", "HAS_RELEASE", "HAS_DOWNLOAD", "DOCUMENTED_BY", "SUPPORTED_BY_EVIDENCE", "TESTED_BY", "USED_FOR", "SUPERSEDES", "INTEGRATES_WITH", "VISUALIZED_BY", "PRODUCES", "CONSUMES", "RESEARCHED_UNDER"]}, "target": {"type": "string"}, "note": {"type": ["string", "null"]}}}},

    "canonical_url": {"type": ["string", "null"]},
    "machine_url": {"type": ["string", "null"]},
    "docs": {"type": ["array", "null"], "items": {"type": "string"}},
    "license": {"type": ["string", "null"]},
    "security_note": {"type": ["string", "null"]},
    "prerequisite_to_publication": {"type": ["string", "null"], "description": "What must happen before details appear. For discovery-state work this is honest about the work itself, not only about clearance — implying a built thing awaits paperwork is its own kind of overclaim."},
    "what_will_appear_here": {"type": ["array", "null"], "items": {"type": "string"}, "description": "Categories of information the page will carry once available. Lets an empty page be useful without promising a result."},

    "record": {"type": "object", "additionalProperties": false, "required": ["schema_version", "source"], "properties": {"schema_version": {"const": "1.0.0"}, "source": {"type": "string", "enum": ["WEBSITE_AUTHORED", "APPROVED_PUBLIC_PACKAGE"], "description": "WEBSITE_AUTHORED records describe this website's own infrastructure. Anything describing the Tiffany programme must arrive as an APPROVED_PUBLIC_PACKAGE."}, "package_id": {"type": ["string", "null"]}, "ingested_at": {"type": ["string", "null"]}}}
  }
}