Declarative YAML

Last modified 14 Sep 2026 07:59 UTC
Since 4.11
This functionality is available since version 4.11.
Table of Contents

The SQL Framework supports a declarative YAML form for the connector manifest, schema definitions, and operation handlers, in addition to Groovy scripts.

YAML documents and Groovy scripts are two front-ends over the same builders — a YAML document drives the same live builders the Groovy DSL does, so both forms can be mixed per connector.

This article is part of the SQL connector development reference and guidance materials. See How to develop connectors using the SQL framework for the section introduction.

Use Groovy scripts for anything requiring scripted behavior — custom search queries, where predicates, attribute resolvers. YAML covers declarative table/attribute mapping and operation control. This page and schema customization describe the same schema customization — the YAML form is a declarative subset of the Groovy DSL.

YAML connector manifest

The connector manifest may be named connector.manifest.json, connector.manifest.yaml or connector.manifest.yml — exactly one of the three may be present on the classpath of the connector bundle (the bundle JAR together with the JARs in its lib/ directory; see bundle layout).

connector:
  schema: (1)
    - script: /schema/customize.groovy
    - script: /schema/persons.native.schema.yaml
  operation: (2)
    - script: /handlers/user_ops.groovy
    - script: /handlers/employee.op.yaml
1 List of schema script resources, loaded during initialization. Groovy and YAML schema documents can be mixed.
2 List of operation handler script resources. Groovy and YAML operation documents can be mixed.

A script entry may carry disabled: true — the script is skipped in both real loading and script validation, as if it were not bundled at all.

Paths starting with / are resolved as classpath resources from the root of the classpath.

Native YAML schema documents

A schema document named .native.schema.yaml (or .connid.schema.yaml) is a flat YAML description of object classes under the objectClasses root (one entry per object class; a file may describe several classes). Both file names are accepted and loaded identically.

# /schema/person.native.schema.yaml
objectClasses:
  Person:
    sql:
      table: app_user
    readOnly: true
    attributes:
      user_id:
        connId:
          name: __UID__
        sql:
          type: INT
          primaryKey: true
      user_name:
        connId:
          name: __NAME__
        sql:
          type: VARCHAR(255)
          notNull: true
      user_email:
        connId:
          name: emailAddress
        sql:
          type: VARCHAR(255)
      loginCount:
        sql:
          type: INT

Structure:

Key Description

objectClasses.<name>

The ConnId object class name (the counterpart of objectClass("…​") { …​ })

description / embedded

The corresponding object-class flags (see SQL schema customization)

readOnly

The object class is read-only; create, update, and delete are disabled automatically

onlyExplicitlyListed

Only the explicitly listed attributes are considered (all other discovered columns are ignored)

connId (object-class level)

Built-in attribute alias map, e.g. connId: { UID: user_id } binds UID to the user_id attribute

sql: { table, schema }

The SQL table name (defaults to the object class name) and optional SQL schema qualifier

attributes.<name>

One attribute — the regular attribute settings (description, required, multiValued, creatable, updateable, readable, returnedByDefault, emulated, complexType), the connId: { name, type } mapping (including the UID / NAME built-ins), the inherited json: { name, type, openApiFormat, path } block (the path is an attribute-path string such as $.name.first, default basic JSONPath — or an explicit { type: JSON_POINTER, value: /name/first } mapping), and the sql block below. An empty value ({}) declares the attribute without renaming.

references.<name>

Map of attribute name → reference attribute definition, with objectClass, subtype, role (see reference attributes)

Attribute-level sql keys:

Key Description

name

The SQL column when it differs from the attribute name

type

The SQL column type (INT, BIGINT, SMALLINT, TINYINT, BOOLEAN, VARCHAR(n), NUMBER(p), NUMBER(p, s), VARCHAR2(n), TIMESTAMP(p), INTEGER, …​)

notNull

The column is not nullable

unique

The column is unique

primaryKey

The column is part of the primary key

autoIncrement

The column is auto-incremented

YAML schema documents bind directly into the same live schema builder as Groovy scripts, so they merge with auto-discovered columns exactly like Groovy customizations do — including correlation with discovery and the built-in mapping rules.

Yes — Groovy and YAML customizations can target the same table (object class): both are applied to the same builder and are merged. The only limit is that a property set explicitly in both forms (or set twice, in any combination of Groovy and YAML) is a conflict and fails at script evaluation — declare each property in exactly one place.

Parsing is strict: a file must contain exactly one document, and unknown keys fail fast.

Operation documents

An operation document covers one or more of create, update, or delete per object class, under the same objectClasses root:

# /handlers/employee.op.yaml
objectClasses:
  Employee:
    create:
      enabled: false
Key Description

create: { enabled } / update: { enabled } / delete: { enabled }

Enables or disables the operation (e.g. enabled: false ≙ disableCreate()); readOnly: true on the schema disables all three automatically

Search works out of the box for discovered tables; Groovy remains the front-end for scripted search behavior (custom query implementations, where predicates — see search and custom search).

Groovy to YAML fallback

If a manifest entry references a .groovy resource that is not bundled, the loader transparently falls back to a .yaml/.yml resource with the same base name:

connector:
  schema:
    - script: /schema/users.groovy   # resolves to /schema/users.yaml when only the YAML file is bundled

This makes it possible to migrate a script to YAML incrementally without changing the manifest.

The granularity of combining the two forms is per script resource, per object class, per attribute, and per operation — the manifest lists .groovy and .yaml resources side by side, and each is applied to the same builder. The only limit is the one described above: do not declare the same property explicitly in both (a table and attributes in YAML plus a search customization in Groovy is fine; the same table property in both is not).

Was this page helpful?
YES NO
Thanks for your feedback