Collection

Profile

arke/collection@v1

Required Properties

Optional Properties

Additional properties can be stored in the properties object.

Default Roles

If roles is not provided, the following defaults are used:

{
  "owner": ["*:view", "*:update", "*:create", "collection:update", "collection:manage"],
  "editor": ["*:view", "*:update", "*:create"],
  "viewer": ["*:view"],
  "public": ["*:view"]
}

Action Format

Actions follow the type:verb pattern:

Note: collection:* is not allowed (security restriction). Collection management requires explicit actions like collection:update or collection:manage.

Common Verbs

Type Implications

The entity base type implies all specific types (file, user, folder, etc.), with one exception:

• entity:view implies collection:view (safe to view collection metadata)
• entity:update, entity:create, etc. do NOT imply collection:* (prevents editors from modifying collection settings)

Platform Role Requirement

The public role with *:view action is required by default (platform rule). This ensures collections are publicly viewable. Private collections will likely be available at some future point.

Custom Roles

Custom roles can be defined with any combination of valid actions:

{
  "transcriber": ["*:view", "file:update"],
  "reviewer": ["*:view", "file:update", "file:create"]
}

Role Name Validation

• Must start with a letter
• Can contain letters, numbers, underscores, and hyphens
• Maximum 64 characters
• Pattern: ^[a-zA-Z][a-zA-Z0-9_-]*$

Example

A collection containing the text of Moby Dick:

{
  "schema": "arke/eidos@v1",
  "id": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "type": "collection",
  "properties": {
    "label": "Moby Dick",
    "description": "The complete text of Herman Melville's Moby Dick",
    "roles": {
      "owner": ["*:view", "*:update", "*:create", "collection:update", "collection:manage"],
      "editor": ["*:view", "*:update", "*:create"],
      "viewer": ["*:view"],
      "public": ["*:view"]
    },
    "_profile_version": "v1"
  },
  "relationships": [
    { "predicate": "public", "peer": "*", "peer_type": "wildcard" },
    { "predicate": "owner", "peer": "01JISHMAEL...", "peer_type": "user", "properties": { "granted_at": "2024-01-15T10:00:00Z", "granted_by": "01JISHMAEL..." } },
    { "predicate": "contains", "peer": "01KFNR0Z394A878Y5AQ63MQEM2", "peer_type": "file" }
  ]
}

Relationships

Role Assignments

Role names are used as predicates. Peer must be user, group, or * (wildcard for public):

{ "predicate": "owner", "peer": "01JISHMAEL...", "peer_type": "user" }
{ "predicate": "editor", "peer": "01JQUEEQUEG...", "peer_type": "user" }
{ "predicate": "public", "peer": "*", "peer_type": "wildcard" }

Temporal Role Assignments

Role assignments can include temporal metadata in the properties object:

{
  "predicate": "editor",
  "peer": "01JQUEEQUEG...",
  "peer_type": "user",
  "properties": {
    "granted_at": "2024-01-15T10:00:00Z",
    "granted_by": "01JISHMAEL...",
    "expires_at": "2024-02-15T10:00:00Z"
  }
}

Content Relationships

{ "predicate": "contains", "peer": "01KFNR0Z394A878Y5AQ63MQEM2", "peer_type": "file", "peer_label": "moby-dick.txt" }

Validation Rules

• Must have a non-empty label string
• If roles is provided, all actions must be valid registered actions or valid wildcards
• Role names must match the validation pattern (^[a-zA-Z][a-zA-Z0-9_-]*$)
• Must include the public role with *:view action (platform requirement, unless user has subscription)
• Role assignments (relationships) must target user, group, or wildcard peer types
• The public wildcard relationship is automatically added on collection creation

Protected Properties

The following properties cannot be set via the generic properties bag and must use dedicated operations: