Collection

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vertesiahq/json-schema/vertesiahq-collection-schema.json",
  "title": "Collection",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vertesiahq-collections-api-openapi.yml#/components/schemas/Collection",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the object"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name or title"
    },
    "description": {
      "type": "string",
      "description": "Optional detailed description of the object"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional array of categorization tags"
    },
    "updated_by": {
      "type": "string",
      "description": "Identifier of the user who last modified the object"
    },
    "created_by": {
      "type": "string",
      "description": "Identifier of the user who created the object"
    },
    "created_at": {
      "type": "string",
      "description": "ISO timestamp of when the object was created"
    },
    "updated_at": {
      "type": "string",
      "description": "ISO timestamp of when the object was last updated"
    },
    "dynamic": {
      "type": "boolean",
      "description": "A flag to indicate if the collection is dynamic or static. If the collection is dynamic, the members are determined by a query using the query field. If the collection is static, the members are explicitly defined using the members array."
    },
    "status": {
      "$ref": "#/$defs/CollectionStatus"
    },
    "type": {
      "$ref": "#/$defs/ContentObjectTypeRef"
    },
    "skip_head_sync": {
      "type": "boolean",
      "description": "A flag to indicate whether to track and sync member HEAD revisions. The default is to sync HEAD revisions for collection members (skip_head_sync: false)"
    },
    "parents": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "The parent collections if any. A collection can have multiple parents."
    },
    "table_layout": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ColumnLayout"
      },
      "description": "The table layout to use for the collection. The layout defined in the type could serve as a fallback if not defined here."
    },
    "allowed_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The allowed types for the collection."
    },
    "properties": {
      "type": "object",
      "additionalProperties": true
    },
    "query": {
      "type": "object",
      "additionalProperties": true
    },
    "security": {
      "$ref": "#/$defs/StringArrayMap"
    },
    "sensitivity": {
      "type": "number",
      "description": "BLP sensitivity level — propagated to member documents (max across collections)"
    },
    "compartments": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Compartments — propagated to member documents (union across collections)"
    },
    "shared": {
      "type": "boolean",
      "description": "Effective shared state: true iff the collection is a member of an effectively-shared parent collection (inherited; sync-managed). Combine with shared_root for full readability."
    },
    "shared_root": {
      "type": "boolean",
      "description": "True iff the collection was explicitly shared via the API (a root of the project shared space). Never set by the sync."
    },
    "shared_properties": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of property names from the collection's properties that should be shared with (injected into) member objects. These properties will be propagated to all members of this collection and merged as arrays."
    },
    "user_permissions": {
      "$ref": "#/$defs/ContentObjectUserPermissions",
      "description": "Computed per-request permissions for the current user on this collection. Not stored — computed on the fly from the collection's security field (same semantics as a content object's user_permissions)."
    }
  },
  "required": [
    "id",
    "name",
    "updated_by",
    "created_by",
    "created_at",
    "updated_at",
    "dynamic",
    "status",
    "skip_head_sync"
  ],
  "additionalProperties": false,
  "$defs": {
    "CollectionStatus": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ]
    },
    "ColumnLayout": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string",
          "description": "The path of the field to use (e.g. \"properties.title\")"
        },
        "name": {
          "type": "string",
          "description": "The name to display in the table column"
        },
        "type": {
          "type": "string",
          "description": "The type of the field specifies how the rendering will be done. If not specified the string type will be used. The type may contain additional parameters prepended using a web-like query string syntax: date?LLL"
        },
        "fallback": {
          "type": "string",
          "description": "Path of an alternate field to display when the primary field is absent"
        },
        "default": {
          "description": "A default value to be used if the field is not present in the object"
        }
      },
      "required": [
        "field",
        "name"
      ],
      "additionalProperties": false
    },
    "ContentObjectTypeRef": {
      "oneOf": [
        {
          "$ref": "#/$defs/StoredTypeRef"
        },
        {
          "$ref": "#/$defs/InCodeTypeRef"
        }
      ],
      "type": "object",
      "required": [
        "ref_type"
      ]
    },
    "ContentObjectUserPermissions": {
      "type": "object",
      "properties": {
        "can_write": {
          "type": "boolean"
        },
        "can_delete": {
          "type": "boolean"
        }
      },
      "required": [
        "can_write",
        "can_delete"
      ],
      "additionalProperties": false,
      "description": "Computed per-request permissions for the current user on a content object. Not stored in the database — computed on the fly by the API from the object's security field."
    },
    "InCodeTypeRef": {
      "type": "object",
      "properties": {
        "ref_type": {
          "type": "string",
          "const": "incode"
        },
        "id": {
          "type": "string",
          "description": "Namespaced identifier for in-code types (e.g. \"sys:Invoice\", \"app:myapp:Contract\")"
        },
        "name": {
          "type": "string"
        },
        "default_view": {
          "type": "string",
          "enum": [
            "auto",
            "text",
            "pdf",
            "image",
            "properties"
          ],
          "description": "Display hint from the type's intake policy (`intake.default_view`). Enriched by the API on single-object reads so clients can pick the initial view without fetching the type. Absent on list responses and older servers."
        }
      },
      "required": [
        "ref_type",
        "id",
        "name"
      ],
      "additionalProperties": false
    },
    "StoredTypeRef": {
      "type": "object",
      "properties": {
        "ref_type": {
          "type": "string",
          "const": "stored"
        },
        "id": {
          "type": "string",
          "description": "MongoDB ObjectId string for stored types"
        },
        "name": {
          "type": "string"
        },
        "default_view": {
          "type": "string",
          "enum": [
            "auto",
            "text",
            "pdf",
            "image",
            "properties"
          ],
          "description": "Display hint from the type's intake policy (`intake.default_view`). Enriched by the API on single-object reads so clients can pick the initial view without fetching the type. Absent on list responses and older servers."
        }
      },
      "required": [
        "ref_type",
        "id",
        "name"
      ],
      "additionalProperties": false
    },
    "StringArrayMap": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}