pattern.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://ethsystems.org/schemas/pattern.json",
  "title": "EthSystems Pattern Frontmatter (v2)",
  "description": "Schema for pattern document frontmatter in EthSystems Map. All v1 aliases have been removed. Structured context_differentiation, crops_context, post_quantum, related_patterns, open_source_implementations, and meta-pattern support are the canonical shape.",
  "type": "object",
  "required": ["title", "status", "maturity", "crops_profile"],
  "properties": {
    "title": {
      "type": "string",
      "pattern": "^Pattern:",
      "description": "Pattern title, must start with 'Pattern:'"
    },
    "status": {
      "type": "string",
      "enum": ["draft", "ready"],
      "description": "Document status"
    },
    "maturity": {
      "type": "string",
      "enum": ["research", "concept", "testnet", "production"],
      "description": "Technology maturity. research (paper only), concept (spec, no code), testnet (PoC/pilot), production (mainnet with real usage)."
    },
    "type": {
      "type": "string",
      "enum": ["standard", "meta"],
      "description": "Pattern kind. 'meta' patterns aggregate sub_patterns and may omit crops_profile, Protocol, and Example. Defaults to 'standard' when absent."
    },
    "layer": {
      "type": "string",
      "enum": ["L1", "L2", "offchain", "hybrid"],
      "description": "Primary architectural layer"
    },
    "last_reviewed": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last review date in YYYY-MM-DD format"
    },
    "works-best-when": {
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ],
      "description": "Conditions when this pattern is optimal"
    },
    "avoid-when": {
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ],
      "description": "Conditions when to avoid this pattern"
    },
    "standards": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Standards this pattern relies on (ERC-20, EIP-7573, ISO-20022, etc.)."
    },
    "related_patterns": {
      "type": "object",
      "description": "Cross-references to other patterns. Slugs match patterns/pattern-<slug>.md.",
      "properties": {
        "requires": {
          "type": "array",
          "items": { "type": "string", "pattern": "^pattern-[a-z0-9-]+$" },
          "description": "Hard dependencies. Can't implement this without them."
        },
        "composes_with": {
          "type": "array",
          "items": { "type": "string", "pattern": "^pattern-[a-z0-9-]+$" },
          "description": "Works well together, optional."
        },
        "alternative_to": {
          "type": "array",
          "items": { "type": "string", "pattern": "^pattern-[a-z0-9-]+$" },
          "description": "Competing approach to the same problem."
        },
        "see_also": {
          "type": "array",
          "items": { "type": "string", "pattern": "^pattern-[a-z0-9-]+$" },
          "description": "Related for context."
        }
      },
      "additionalProperties": false
    },
    "open_source_implementations": {
      "type": "array",
      "description": "Known open-source implementations. Plural, neutral.",
      "items": {
        "type": "object",
        "required": ["url", "description"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "language": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "sub_patterns": {
      "type": "array",
      "description": "Children of a meta-pattern. Required when type: meta.",
      "items": {
        "type": "object",
        "required": ["name", "pattern", "crops_summary"],
        "properties": {
          "name": { "type": "string" },
          "pattern": {
            "type": "string",
            "pattern": "^pattern-[a-z0-9-]+$",
            "description": "Slug resolved to patterns/pattern-<slug>.md"
          },
          "crops_summary": {
            "type": "string",
            "description": "One-line CROPS trade-off summary for this child"
          }
        },
        "additionalProperties": false
      }
    },
    "context": {
      "type": "string",
      "enum": ["i2i", "i2u", "both"],
      "description": "Applicable relationship type"
    },
    "context_differentiation": {
      "type": "object",
      "description": "How the pattern applies differently in I2I vs I2U. Required when context: both (enforced by validator).",
      "properties": {
        "i2i": {
          "type": "string",
          "minLength": 1,
          "description": "How this plays out between institutions"
        },
        "i2u": {
          "type": "string",
          "minLength": 1,
          "description": "How this plays out for user-facing deployments; what extra protections are needed"
        }
      },
      "additionalProperties": false
    },
    "crops_profile": {
      "description": "CROPS dimension assessment. Use the string 'n/a' for meta/evaluation patterns that do not implement privacy directly.",
      "oneOf": [
        {
          "type": "string",
          "enum": ["n/a"]
        },
        {
          "type": "object",
          "required": ["cr", "o", "p", "s"],
          "properties": {
            "cr": {
              "type": "string",
              "enum": ["high", "medium", "low", "none"],
              "description": "Censorship resistance"
            },
            "o": {
              "type": "string",
              "enum": ["yes", "partial", "no"],
              "description": "Openness: source availability, open standards, exit paths, forkability. The 'O' in CROPS — broader than just open source."
            },
            "p": {
              "type": "string",
              "enum": ["full", "partial", "none"],
              "description": "Privacy: full (private from everyone), partial (selective disclosure required), none (public or institution sees all)"
            },
            "s": {
              "type": "string",
              "enum": ["high", "medium", "low"],
              "description": "Security: strength of guarantees (cryptographic assumptions, decentralization, trust model)"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "crops_context": {
      "type": "object",
      "description": "Narrative context for each CROPS dimension. Explains where the badges drift up or down in practice.",
      "properties": {
        "cr": { "type": "string" },
        "o": { "type": "string" },
        "p": { "type": "string" },
        "s": { "type": "string" }
      },
      "additionalProperties": false
    },
    "visibility": {
      "type": "object",
      "description": "Optional four-slot visibility matrix for transaction-level patterns: who sees what.",
      "properties": {
        "counterparty": { "type": "array", "items": { "type": "string" } },
        "chain": { "type": "array", "items": { "type": "string" } },
        "regulator": { "type": "array", "items": { "type": "string" } },
        "public": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "post_quantum": {
      "type": "object",
      "description": "Post-quantum exposure summary.",
      "properties": {
        "risk": {
          "type": "string",
          "enum": ["high", "medium", "low"]
        },
        "vector": { "type": "string" },
        "mitigation": { "type": "string" }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}