{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/DecentralizedGeo/dgeo/refs/heads/main/json-schema/schema.json",
  "title": "Decentralized Geospatial Extension",
  "description": "Associates STAC Items and Collections with decentralized web resources. This extension enables queryable CID-based discovery while providing technical DAG metadata at the asset level.",
  "type": "object",
  "required": ["stac_extensions"],
  "properties": {
    "stac_extensions": {
      "type": "array",
      "contains": {
        "const": "https://raw.githubusercontent.com/DecentralizedGeo/dgeo/refs/heads/main/json-schema/schema.json"
      }
    }
  },
  "oneOf": [
    {
      "title": "STAC Item",
      "$comment": "This is the schema for STAC Items.",
      "type": "object",
      "required": ["type", "properties", "assets"],
      "properties": {
        "type": {
          "const": "Feature"
        },
        "properties": {
          "$ref": "#/definitions/dgeo_fields"
        },
        "assets": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/dgeo_asset_fields"
          }
        }
      }
    },
    {
      "title": "STAC Collection",
      "$comment": "This is the schema for STAC Collections.",
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "const": "Collection"
        },
        "assets": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/dgeo_asset_fields"
          }
        }
      },
      "allOf": [
        {
          "$ref": "#/definitions/dgeo_fields"
        }
      ]
    },
    {
      "title": "STAC Catalog",
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "const": "Catalog"
        }
      }
    }
  ],
  "definitions": {
    "dgeo_fields": {
      "type": "object",
      "required": ["dgeo:cids"],
      "properties": {
        "dgeo:cids": {
          "type": "array",
          "description": "REQUIRED. Array of Content Identifiers (CIDs) associated with this Item or Collection. Each CID MUST be immutable; mutable pointers such as IPNS MUST NOT be included. This field is queryable via pgstac and STAC API CQL2 filters.",
          "items": {
            "type": "string",
            "pattern": "^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,})$"
          },
          "minItems": 1,
          "uniqueItems": true
        },
        "dgeo:piece_cids": {
          "type": "array",
          "description": "OPTIONAL. Array of Filecoin Piece CIDs (commP) used for storage verification and proof-of-replication workflows. This field is queryable via pgstac and STAC API CQL2 filters.",
          "items": {
            "type": "string",
            "pattern": "^baga6ea[a-z2-7]{52,}$"
          },
          "uniqueItems": true
        }
      }
    },
    "dgeo_asset_fields": {
      "type": "object",
      "properties": {
        "dgeo:cid": {
          "type": "string",
          "description": "OPTIONAL. The CID that this asset represents. When present, this CID MUST also appear in the parent Item or Collection's dgeo:cids array. This field enables programmatic correlation between queryable CIDs and specific assets, particularly when hrefs use HTTP gateway URLs that don't directly expose the CID.",
          "pattern": "^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,})$"
        },
        "dgeo:piece_cid": {
          "type": "string",
          "description": "OPTIONAL. The Filecoin Piece CID (commP) that this asset is committed to. When present, this CID MUST also appear in the parent Item or Collection's dgeo:piece_cids array.",
          "pattern": "^baga6ea[a-z2-7]{52,}$"
        },
        "dgeo:cid_profile": {
          "type": "object",
          "description": "OPTIONAL. Technical details about how the CID's DAG was generated (chunking, hashing, layout, sharding, etc.). This metadata enables reproducible DAG reconstruction and verification workflows.",
          "additionalProperties": true,
          "properties": {
            "cid_version": {
              "type": "integer",
              "enum": [0, 1],
              "description": "RECOMMENDED. Content Identifier (CID) version (0 or 1) specifying the format's structure and encoding."
            },
            "hash_function": {
              "type": "string",
              "description": "RECOMMENDED. Multihash function to use (e.g., \"sha2-256\")."
            },
            "chunking_algorithm": {
              "type": "string",
              "description": "RECOMMENDED. Algorithm used to split files into chunks (e.g., \"fixed-size\", \"rabin\")."
            },
            "chunk_size": {
              "type": "integer",
              "description": "OPTIONAL. Maximum size of each chunk in bytes."
            },
            "dag_width": {
              "type": "integer",
              "description": "OPTIONAL. Maximum number of children per node in the DAG."
            },
            "dag_layout": {
              "type": "string",
              "description": "RECOMMENDED. Layout of the DAG (e.g., \"balanced\", \"balanced-packed\", \"trickle\")."
            },
            "empty_directories": {
              "type": "boolean",
              "description": "OPTIONAL. Whether empty directories are included in the DAG."
            },
            "hamt_directory_fanout": {
              "type": "string",
              "description": "OPTIONAL. Maximum number of block entries per HAMT directory node (e.g. \"256 blocks\")."
            },
            "hamt_directory_threshold": {
              "type": "string",
              "description": "OPTIONAL. The HAMTDirectory threshold determines when a directory converts to a HAMT structure based on its estimated size and is evaluated using `links-count` (child count), `links-bytes` (sum of link name and hash lengths), or `block-bytes` (full serialized node size)."
            },
            "hamt_switch_comparison": {
              "type": "string",
              "description": "OPTIONAL. Comparison operator used when evaluating HAMTDirectory thresholds for switching to a HAMT structure. Allowed values are \">=\" and \">\"."
            },
            "leaves": {
              "type": "string",
              "description": "OPTIONAL. Determines whether file data is stored in a dag-pb-wrapped block (with metadata) or as raw bytes (without metadata)."
            },
            "hidden_entities": {
              "type": "boolean",
              "description": "OPTIONAL. Whether hidden entities (including dot files) are included in the DAG."
            },
            "symlinks": {
              "type": "string",
              "description": "OPTIONAL. Method for handling symbolic links (e.g., 'preserve', 'followed', 'skipped')."
            },
            "mode_permissions": {
              "type": "boolean",
              "description": "OPTIONAL. POSIX file permissions included in the DAG."
            },
            "mod_time": {
              "type": "boolean",
              "description": "OPTIONAL. File modification time included in the DAG."
            }
          }
        }
      }
    }
  }
}