schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/OpenAssetIO/OpenAssetIO-Manager-BAL/main/schema.json",
  "title": "BAL Library File",
  "description": "The data store that backs an instance of the BAL manager",
  "type": "object",
  "properties": {
    "capabilities": {
      "description": "List of capabilities that BAL should advertise",
      "type": "array",
      "items": {
        "type": "string",
        "description": "The name of a capability, as defined in ManagerInterface.kCapabilityNames"
      },
      "additionalProperties": false
    },
    "variables": {
      "description": "Arbitrary variables to be substituted in string trait properties",
      "type": "object",
      "patternProperties": {
        "[a-zA-Z_]+": {
          "description": "The value to substitute",
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "managementPolicy": {
      "description": "Custom managementPolicy responses",
      "type": "object",
      "properties": {
        "read": {
          "type": "object",
          "description": "Custom managementPolicy responses for read access contexts",
          "properties": {
            "default": {
              "description": "The default policy unless an exception is specified",
              "type": "object",
              "patternProperties": {
                ".*": {
                  "description": "The trait's property values.",
                  "type": "object",
                  "patternProperties": {
                    ".*": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    }
                  }
                }
              }
            },
            "overrideByTraitSet": {
              "descriptions": "Custom policies that override the default",
              "type": "array",
              "items": {
                "type": "object",
                "description": "A policy for a specific trait set, that must match the request exactly",
                "properties": {
                  "traitSet": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "policy": {
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": [
                              "string",
                              "number",
                              "boolean"
                            ]
                          }
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false,
                "required": ["traitSet", "policy"]
              }
            }
          },
          "required": ["default"],
          "additionalProperties": false
        },
        "write": {
          "type": "object",
          "description": "Custom managementPolicy responses for write access contexts",
          "properties": {
            "default": {
              "description": "The default policy unless an exception is specified",
              "type": "object",
              "patternProperties": {
                ".*": {
                  "description": "The trait's property values.",
                  "type": "object",
                  "patternProperties": {
                    ".*": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    }
                  }
                }
              }
            },
            "overrideByTraitSet": {
              "descriptions": "Custom policies that override the default",
              "type": "array",
              "items": {
                "type": "object",
                "description": "A policy for a specific trait set, that must match the request exactly",
                "properties": {
                  "traitSet": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "policy": {
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": [
                              "string",
                              "number",
                              "boolean"
                            ]
                          }
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false,
                "required": ["traitSet", "policy"]
              }
            }
          },
          "required": ["default"],
          "additionalProperties": false
        },
        "required": {
          "type": "object",
          "description": "Custom managementPolicy responses for required access contexts",
          "properties": {
            "default": {
              "description": "The default policy unless an exception is specified",
              "type": "object",
              "patternProperties": {
                ".*": {
                  "description": "The trait's property values.",
                  "type": "object",
                  "patternProperties": {
                    ".*": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    }
                  }
                }
              }
            },
            "overrideByTraitSet": {
              "descriptions": "Custom policies that override the default",
              "type": "array",
              "items": {
                "type": "object",
                "description": "A policy for a specific trait set, that must match the request exactly",
                "properties": {
                  "traitSet": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "policy": {
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": [
                              "string",
                              "number",
                              "boolean"
                            ]
                          }
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false,
                "required": ["traitSet", "policy"]
              }
            }
          },
          "required": ["default"],
          "additionalProperties": false
        },
        "createRelated": {
          "type": "object",
          "description": "Custom managementPolicy responses for create related access contexts",
          "properties": {
            "default": {
              "description": "The default policy unless an exception is specified",
              "type": "object",
              "patternProperties": {
                ".*": {
                  "description": "The trait's property values.",
                  "type": "object",
                  "patternProperties": {
                    ".*": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    }
                  }
                }
              }
            },
            "overrideByTraitSet": {
              "descriptions": "Custom policies that override the default",
              "type": "array",
              "items": {
                "type": "object",
                "description": "A policy for a specific trait set, that must match the request exactly",
                "properties": {
                  "traitSet": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "policy": {
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": [
                              "string",
                              "number",
                              "boolean"
                            ]
                          }
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false,
                "required": ["traitSet", "policy"]
              }
            }
          },
          "required": ["default"],
          "additionalProperties": false
        },
        "managerDriven": {
          "type": "object",
          "description": "Custom managementPolicy responses for manager driven access contexts",
          "properties": {
            "default": {
              "description": "The default policy unless an exception is specified",
              "type": "object",
              "patternProperties": {
                ".*": {
                  "description": "The trait's property values.",
                  "type": "object",
                  "patternProperties": {
                    ".*": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    }
                  }
                }
              }
            },
            "overrideByTraitSet": {
              "descriptions": "Custom policies that override the default",
              "type": "array",
              "items": {
                "type": "object",
                "description": "A policy for a specific trait set, that must match the request exactly",
                "properties": {
                  "traitSet": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "policy": {
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": [
                              "string",
                              "number",
                              "boolean"
                            ]
                          }
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false,
                "required": ["traitSet", "policy"]
              }
            }
          },
          "required": ["default"],
          "additionalProperties": false
        }
      },
      "required": ["read", "write"],
      "additionalProperties": false
    },
    "defaultEntities": {
      "description": "A mapping of intended access and trait set to appropriate default entity",
      "type": "object",
      "properties": {
        "read": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "traits": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "entity": {
                "type": ["string", "null"]
              }
            },
            "required": [
              "traits",
              "entity"
            ]
          }
        },
        "write": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "traits": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "entity": {
                "type": ["string", "null"]
              }
            },
            "required": [
              "traits",
              "entity"
            ]
          }
        },
        "createRelated": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "traits": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "entity": {
                "type": ["string", "null"]
              }
            },
            "required": [
              "traits",
              "entity"
            ]
          }
        }
      }
    },
    "entities": {
      "description": "The entities in the library, they key is used as the entity name.",
      "type": "object",
      "patternProperties": {
        ".*": {
          "type": "object",
          "properties": {
            "versions": {
              "type": "array",
              "description": "The versions array holds the actual data, the array index is used as the version number.",
              "minItems": 0,
              "items": {
                "type": "object",
                "description": "The data for any given entity.",
                "properties": {
                  "traits": {
                    "description": "Traits and their associated properties for the entity.",
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": ["string", "number", "boolean"]
                          }
                        }
                      }
                    }
                  }
                },
                "required": ["traits"],
                "additionalProperties": false
              }
            },
            "overrideByAccess": {
              "type": "object",
              "description": "Override of version data per access mode.",
              "patternProperties": {
                ".*": {
                  "type": ["object", "null"],
                  "description": "Mapping of access mode to entity version data.",
                  "properties": {
                    "traits": {
                      "description": "Traits and their associated properties for the entity.",
                      "type": "object",
                      "patternProperties": {
                        ".*": {
                          "description": "The trait's property values.",
                          "type": "object",
                          "patternProperties": {
                            ".*": {
                              "type": [
                                "string",
                                "number",
                                "boolean"
                              ]
                            }
                          }
                        }
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            },
            "relations": {
              "type": "array",
              "description": "Descriptions of entity relationships. These combine a description of the nature of the relationship - using traits, and a list of related entities.",
              "items": {
                "type": "object",
                "description": "The definition of a particular relationship",
                "properties": {
                  "traits": {
                    "description": "Traits and their associated properties that describe the nature of the relationship itself (not the related entities).",
                    "type": "object",
                    "patternProperties": {
                      ".*": {
                        "description": "The trait's property values.",
                        "type": "object",
                        "patternProperties": {
                          ".*": {
                            "type": ["string", "number", "boolean"]
                          }
                        }
                      }
                    }
                  },
                  "entities": {
                    "type": "array",
                    "description": "The entities that are referenced by this relationship.",
                    "minItems": 1,
                    "items": {
                      "description": "The name of the BAL entity as it appears in the top-level 'entities' object.",
                      "type": "string"
                    }
                  }
                },
                "required": ["traits", "entities"],
                "additionalProperties": false
              }
            }
          },
          "required": ["versions"],
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "required": ["entities"],
  "additionalProperties": false
}