Package ai.vectros.types

Class SchemaRequest.Builder

java.lang.Object
ai.vectros.types.SchemaRequest.Builder
All Implemented Interfaces:
SchemaRequest._FinalStage, SchemaRequest.DisplayNameStage, SchemaRequest.TypeNameStage
Enclosing class:
SchemaRequest
public static final class SchemaRequest.Builder extends Object implements SchemaRequest.TypeNameStage, SchemaRequest.DisplayNameStage, SchemaRequest._FinalStage

  • Method Details

    • from

      public SchemaRequest.Builder from(SchemaRequest other)
      Specified by:
      from in interface SchemaRequest.TypeNameStage

    • typeName

      public SchemaRequest.DisplayNameStage typeName(@NotNull @NotNull String typeName)

      Unique type identifier for this schema. Immutable after creation.

      Unique type identifier for this schema. Immutable after creation.

      Specified by:
      typeName in interface SchemaRequest.TypeNameStage
      Returns:
      Reference to this so that method calls can be chained together.

    • displayName

      public SchemaRequest._FinalStage displayName(@NotNull @NotNull String displayName)

      Human-readable display name for this type, shown in UIs.

      Human-readable display name for this type, shown in UIs.

      Specified by:
      displayName in interface SchemaRequest.DisplayNameStage
      Returns:
      Reference to this so that method calls can be chained together.

    • basedOn

      public SchemaRequest._FinalStage basedOn(String basedOn)

      The id of an existing schema this one is a CUSTOMIZATION of, when a schema named typeName already exists in this context — required in that case (a same-named schema without it is rejected: "specify basedOn"), and must be omitted when this create is the FIRST schema under that name (it becomes that name's shared base, and must be created with no userId/scopes — a root/unscoped credential). Must point directly at the base (one hop); a variant of a variant is not yet supported. Immutable once set. Every same-named schema in a context is provably related through this chain — see the recordType-shadowing design doc.

      Specified by:
      basedOn in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • basedOn

      public SchemaRequest._FinalStage basedOn(Optional<String> basedOn)

      The id of an existing schema this one is a CUSTOMIZATION of, when a schema named typeName already exists in this context — required in that case (a same-named schema without it is rejected: "specify basedOn"), and must be omitted when this create is the FIRST schema under that name (it becomes that name's shared base, and must be created with no userId/scopes — a root/unscoped credential). Must point directly at the base (one hop); a variant of a variant is not yet supported. Immutable once set. Every same-named schema in a context is provably related through this chain — see the recordType-shadowing design doc.

      Specified by:
      basedOn in interface SchemaRequest._FinalStage

    • scopes

      public SchemaRequest._FinalStage scopes(List<String> scopes)

      The schema's scope ownership, as namespace:value entries (at most 2 namespaces) — for example ["org:6ba7b810-9dad-11d1-80b4-00c04fd430c8", "group:eng-team"]. org and client are reserved namespace names, registered like any other; others are namespaces you registered yourself (lowercase, 2-32 chars). A value is 1-128 characters: a letter or digit first, then letters, digits, _ or -. Resolve a namespace's UUID from your own identifier with GET /v1/entities/{namespace}?externalId=. Optional — omit for an account-wide shared schema. When supplied, this is the schema's COMPLETE scope declaration: each entry must fall inside the data_scope of a single clause of your credential that also grants this write — your identity supplies the DEFAULT value when you state none, it does not limit which value you may state. On update, omit to leave ownership unchanged, or supply the complete new selection ([] clears it). Filter lists by these values with ?scope=.

      Specified by:
      scopes in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • scopes

      public SchemaRequest._FinalStage scopes(Optional<List<String>> scopes)

      The schema's scope ownership, as namespace:value entries (at most 2 namespaces) — for example ["org:6ba7b810-9dad-11d1-80b4-00c04fd430c8", "group:eng-team"]. org and client are reserved namespace names, registered like any other; others are namespaces you registered yourself (lowercase, 2-32 chars). A value is 1-128 characters: a letter or digit first, then letters, digits, _ or -. Resolve a namespace's UUID from your own identifier with GET /v1/entities/{namespace}?externalId=. Optional — omit for an account-wide shared schema. When supplied, this is the schema's COMPLETE scope declaration: each entry must fall inside the data_scope of a single clause of your credential that also grants this write — your identity supplies the DEFAULT value when you state none, it does not limit which value you may state. On update, omit to leave ownership unchanged, or supply the complete new selection ([] clears it). Filter lists by these values with ?scope=.

      Specified by:
      scopes in interface SchemaRequest._FinalStage

    • userId

      public SchemaRequest._FinalStage userId(String userId)

      Owning user — the Vectros-assigned UUID of a user in your account. Optional; omit to create an account-wide shared schema. With an API key, this sets the schema's owner explicitly. With a scoped token the owning user is attributed by the server from your credential and cannot be set to a different user; supplying one that conflicts is rejected.

      Specified by:
      userId in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • userId

      public SchemaRequest._FinalStage userId(Optional<String> userId)

      Owning user — the Vectros-assigned UUID of a user in your account. Optional; omit to create an account-wide shared schema. With an API key, this sets the schema's owner explicitly. With a scoped token the owning user is attributed by the server from your credential and cannot be set to a different user; supplying one that conflicts is rejected.

      Specified by:
      userId in interface SchemaRequest._FinalStage

    • active

      public SchemaRequest._FinalStage active(Boolean active)

      Whether this schema is active. An inactive schema rejects creation of new records of its type.

      Specified by:
      active in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • active

      public SchemaRequest._FinalStage active(Optional<Boolean> active)

      Whether this schema is active. An inactive schema rejects creation of new records of its type.

      Specified by:
      active in interface SchemaRequest._FinalStage

    • addAllAllowedSurfaces

      public SchemaRequest._FinalStage addAllAllowedSurfaces(List<SchemaRequestAllowedSurfacesItem> allowedSurfaces)

      Which typed surfaces may bind this schema by its id: record, document, user, or entity. Required and must be non-empty. Identity entities in ANY namespace — org, client, or one you registered, such as team — bind under the single entity surface; use the schema's typeName to distinguish them, not the surface. A schema may list several surfaces (for a shared type usable on both records and documents). This drives surface-scoped schema listing (GET /v1/schemas?surface=) and is enforced at bind time — for example, a document cannot bind a record-only schema. A user-surfaced schema is control-plane managed and can only be created, updated, or deleted with a root API key — a partner user is tenant-global, so its schema has one tenant-wide home. An entity-surfaced schema, by contrast, is writable by an ordinary scoped credential holding schemas:c/u/d, and is homed in that credential's own app context. record/document schemas are unaffected either way — any credential holding the matching scope may write them, as before.

      Specified by:
      addAllAllowedSurfaces in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • addAllowedSurfaces

      public SchemaRequest._FinalStage addAllowedSurfaces(SchemaRequestAllowedSurfacesItem allowedSurfaces)

      Which typed surfaces may bind this schema by its id: record, document, user, or entity. Required and must be non-empty. Identity entities in ANY namespace — org, client, or one you registered, such as team — bind under the single entity surface; use the schema's typeName to distinguish them, not the surface. A schema may list several surfaces (for a shared type usable on both records and documents). This drives surface-scoped schema listing (GET /v1/schemas?surface=) and is enforced at bind time — for example, a document cannot bind a record-only schema. A user-surfaced schema is control-plane managed and can only be created, updated, or deleted with a root API key — a partner user is tenant-global, so its schema has one tenant-wide home. An entity-surfaced schema, by contrast, is writable by an ordinary scoped credential holding schemas:c/u/d, and is homed in that credential's own app context. record/document schemas are unaffected either way — any credential holding the matching scope may write them, as before.

      Specified by:
      addAllowedSurfaces in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • allowedSurfaces

      public SchemaRequest._FinalStage allowedSurfaces(List<SchemaRequestAllowedSurfacesItem> allowedSurfaces)

      Which typed surfaces may bind this schema by its id: record, document, user, or entity. Required and must be non-empty. Identity entities in ANY namespace — org, client, or one you registered, such as team — bind under the single entity surface; use the schema's typeName to distinguish them, not the surface. A schema may list several surfaces (for a shared type usable on both records and documents). This drives surface-scoped schema listing (GET /v1/schemas?surface=) and is enforced at bind time — for example, a document cannot bind a record-only schema. A user-surfaced schema is control-plane managed and can only be created, updated, or deleted with a root API key — a partner user is tenant-global, so its schema has one tenant-wide home. An entity-surfaced schema, by contrast, is writable by an ordinary scoped credential holding schemas:c/u/d, and is homed in that credential's own app context. record/document schemas are unaffected either way — any credential holding the matching scope may write them, as before.

      Specified by:
      allowedSurfaces in interface SchemaRequest._FinalStage

    • storageProfile

      public SchemaRequest._FinalStage storageProfile(SchemaRequestStorageProfile storageProfile)

      Where this type's payload is stored. STANDARD (default): payloads of 4 KB or larger are externalized to S3, smaller ones are stored inline. LOW_LATENCY: always store inline for the lowest read latency. LARGE_PAYLOAD: always externalize to S3, which lifts the 400 KB item-size ceiling. For externalized types, list and lookup responses return only the indexed projection unless you pass includePayload=true.

      Specified by:
      storageProfile in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • storageProfile

      public SchemaRequest._FinalStage storageProfile(Optional<SchemaRequestStorageProfile> storageProfile)

      Where this type's payload is stored. STANDARD (default): payloads of 4 KB or larger are externalized to S3, smaller ones are stored inline. LOW_LATENCY: always store inline for the lowest read latency. LARGE_PAYLOAD: always externalize to S3, which lifts the 400 KB item-size ceiling. For externalized types, list and lookup responses return only the indexed projection unless you pass includePayload=true.

      Specified by:
      storageProfile in interface SchemaRequest._FinalStage

    • indexMode

      public SchemaRequest._FinalStage indexMode(SchemaRequestIndexMode indexMode)

      Default search-index mode for instances of this type — applies to records of this type and to documents bound to this schema, unless the individual record or document sets its own indexMode. HYBRID, SEMANTIC, and TEXT make content searchable; NONE is store-only (the data is persisted, retrievable, and usable for lookups, but not searchable). Omit for no default: a record with no indexMode of its own then defaults to NONE, and a document with no indexMode is rejected.

      Specified by:
      indexMode in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • indexMode

      public SchemaRequest._FinalStage indexMode(Optional<SchemaRequestIndexMode> indexMode)

      Default search-index mode for instances of this type — applies to records of this type and to documents bound to this schema, unless the individual record or document sets its own indexMode. HYBRID, SEMANTIC, and TEXT make content searchable; NONE is store-only (the data is persisted, retrievable, and usable for lookups, but not searchable). Omit for no default: a record with no indexMode of its own then defaults to NONE, and a document with no indexMode is rejected.

      Specified by:
      indexMode in interface SchemaRequest._FinalStage

    • capabilities

      public SchemaRequest._FinalStage capabilities(Map<String,Boolean> capabilities)

      Feature flags for this schema. auditHistory (default true) controls whether a change-history (version) trail is kept for this type's data; setting it false stops recording the trail but never affects your record or document data itself. readAccessLog (default false; opt-in) controls accounting-of-disclosures logging: when true, each governed read of this schema's records writes a retained, subject-enumerable access record. The effective value resolves in order: this schema flag, then your context's default, then the platform default (false).

      Specified by:
      capabilities in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • capabilities

      public SchemaRequest._FinalStage capabilities(Optional<Map<String,Boolean>> capabilities)

      Feature flags for this schema. auditHistory (default true) controls whether a change-history (version) trail is kept for this type's data; setting it false stops recording the trail but never affects your record or document data itself. readAccessLog (default false; opt-in) controls accounting-of-disclosures logging: when true, each governed read of this schema's records writes a retained, subject-enumerable access record. The effective value resolves in order: this schema flag, then your context's default, then the platform default (false).

      Specified by:
      capabilities in interface SchemaRequest._FinalStage

    • renderHints

      public SchemaRequest._FinalStage renderHints(Map<String,RenderHintDef> renderHints)

      UI rendering hints keyed by field id.

      Specified by:
      renderHints in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • renderHints

      public SchemaRequest._FinalStage renderHints(Optional<Map<String,RenderHintDef>> renderHints)

      UI rendering hints keyed by field id.

      Specified by:
      renderHints in interface SchemaRequest._FinalStage

    • lookupFields

      public SchemaRequest._FinalStage lookupFields(List<LookupDef> lookupFields)

      Payload fields to index for direct lookup queries. Maximum 10 lookup fields.

      Specified by:
      lookupFields in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • lookupFields

      public SchemaRequest._FinalStage lookupFields(Optional<List<LookupDef>> lookupFields)

      Payload fields to index for direct lookup queries. Maximum 10 lookup fields.

      Specified by:
      lookupFields in interface SchemaRequest._FinalStage

    • fields

      public SchemaRequest._FinalStage fields(List<FieldDef> fields)

      Field definitions used to validate record payloads. Omit for a bare schema that performs no payload validation.

      Specified by:
      fields in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • fields

      public SchemaRequest._FinalStage fields(Optional<List<FieldDef>> fields)

      Field definitions used to validate record payloads. Omit for a bare schema that performs no payload validation.

      Specified by:
      fields in interface SchemaRequest._FinalStage

    • description

      public SchemaRequest._FinalStage description(String description)

      Optional description of what this schema is for.

      Specified by:
      description in interface SchemaRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • description

      public SchemaRequest._FinalStage description(Optional<String> description)

      Optional description of what this schema is for.

      Specified by:
      description in interface SchemaRequest._FinalStage

    • build

      public SchemaRequest build()
      Specified by:
      build in interface SchemaRequest._FinalStage

    • additionalProperty

      public SchemaRequest.Builder additionalProperty(String key, Object value)
      Specified by:
      additionalProperty in interface SchemaRequest._FinalStage

    • additionalProperties

      public SchemaRequest.Builder additionalProperties(Map<String,Object> additionalProperties)
      Specified by:
      additionalProperties in interface SchemaRequest._FinalStage