Extensions | Runtime Conditions

What an extension owns

Extension Part	What It Does	Example
`dependencies`	References vocabulary owned by other extensions.	`https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml`
`kinds`	Defines Condition categories.	`api`, `datastore`, `cache`
`interfaceTypes`	Defines valid interface types for a kind.	`http` for `api`, `key_value` for `cache`
`conditionFields`	Defines extension-owned fields on Conditions.	`configuration`
`interfaceFields`	Defines extension-owned fields inside `interface`.	`interface.engine`, `interface.operations`
`fieldValues`	Defines allowed values for extension-owned fields.	`redis`, `memcached`, `GET`, `POST`
`schemas`	Defines machine-readable validation.	JSON Schema for HTTP API Conditions

Choosing vocabulary keywords

Each extension keyword answers a different authoring question. Use the smallest keyword that owns the vocabulary you are adding, then use schemas for shape.

Author wants to	Use	Result
Add a Condition category	`kinds`	`kind: aws.object_store`
Add an interface type for a kind	`interfaceTypes`	`interface.type: aws.s3`
Add a top-level Condition field	`conditionFields`	`configuration`, `trust`, `access`
Add a field inside `interface`	`interfaceFields`	`interface.engine`, `interface.bucketClass`
Define portable value choices	`fieldValues`	`redis`, `standard`, `GET`
Validate object shape	`schemas`	Required properties, arrays, conditional rules

Top-level field vs interface field

conditionFields:
  - name: configuration
    appliesToKinds:
      - cache
    appliesToInterfaceTypes:
      - key_value

interfaceFields:
  - name: engine
    targetKind: cache
    targetType: key_value

Field paths point to owned fields

`fieldValues` names allowed values for a field path. It does not create the field; the path must resolve to `interface.type`, an `interfaceFields` entry, or a scoped `conditionFields` entry.

Interface path

interfaceFields:
  - name: bucketClass
    targetKind: aws.object_store
    targetType: aws.s3

fieldValues:
  - field: interface.bucketClass
    targetKind: aws.object_store
    targetType: aws.s3
    values:
      - standard
      - archive

Condition field path with array traversal

conditionFields:
  - name: configuration
    appliesToKinds:
      - cache
    appliesToInterfaceTypes:
      - key_value

fieldValues:
  - field: configuration.env[].property
    targetKind: cache
    targetType: key_value
    values:
      - url
      - hostname
      - port

First-party extension: Common Integrations

The Common Integrations extension defines standard integration vocabulary for APIs, datastores, and caches. Profiles that use `kind: cache` or `interface.type: http` depend on this extension.

common-integrations/common-integrations-v1alpha1.yaml source

metadata:
  id: https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml

spec:
  kinds:
    - name: api
    - name: datastore
    - name: cache

  interfaceTypes:
    - name: http
      targetKind: api
    - name: key_value
      targetKind: cache

Field values make vocabulary deterministic

The extension does not merely say an engine field may exist. It also owns the shared values that validators and adapters can rely on.

Cache engine values

fieldValues:
  - field: interface.engine
    targetKind: cache
    targetType: key_value
    values:
      - redis
      - memcached

HTTP method values

fieldValues:
  - field: interface.operations[].method
    targetKind: api
    targetType: http
    values:
      - GET
      - HEAD
      - POST
      - PUT
      - PATCH
      - DELETE
      - OPTIONS
      - TRACE

Extensions define JSON Schema validation

Schema rules make extension validation portable. The validator can evaluate the profile without interpreting prose.

HTTP API schema excerpt

schemas:
  - id: api-http-interface
    appliesToKind: api
    appliesToInterfaceType: http
    description: Validates HTTP API integration conditions.
    schema:
      type: object
      required:
        - kind
        - interface
      properties:
        kind:
          const: api
        interface:
          type: object
          required:
            - type
          properties:
            type:
              const: http
            operations:
              type: array
              items:
                required:
                  - method
                  - path

First-party extension: Environment Configuration

The Environment Configuration extension adds the `configuration` field to common integration Conditions. It depends on Common Integrations and scopes its field to common-owned kinds and interface types.

env-configuration/env-configuration-v1alpha1.yaml source

spec:
  dependencies:
    - https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml

  conditionFields:
    - name: configuration
      appliesToKinds:
        - api
      appliesToInterfaceTypes:
        - http
    - name: configuration
      appliesToKinds:
        - datastore
      appliesToInterfaceTypes:
        - relational
        - document
    - name: configuration
      appliesToKinds:
        - cache
      appliesToInterfaceTypes:
        - key_value

  fieldValues:
    - field: configuration.env[].property
      targetKind: cache
      targetType: key_value
      values:
        - url
        - hostname
        - port
        - username
        - password
        - token

Declaration packages follow ownership

Common declarations come from `common-integrations/go`. Environment configuration contributes typed options from `env-configuration/go`. The binding manifest is first-party generator metadata; it does not define extension vocabulary.

Dual-import declaration code

import (
  common "github.com/runtimeconditions/extensions/common-integrations/go"
  env "github.com/runtimeconditions/extensions/env-configuration/go"
)

common.Cache("request-cache",
  common.KeyValue(common.Redis),
  env.EnvAlternative(env.Env("url", "REDIS_URL")),
)

Option-only binding manifest

apiVersion: runtimeconditions.io/v1alpha1
kind: RuntimeConditionsBinding

metadata:
  extension: https://runtimeconditions.io/extensions/env-configuration/v1alpha1/runtimeconditions.extension.yaml
  language: go

go:
  importPath: github.com/runtimeconditions/extensions/env-configuration/go
  package: envconfiguration

  options:
    - function: Env
      target: configuration.env[]
      appliesToKinds:
        - api
        - datastore
        - cache
      stringArgs:
        property: 0
        name: 1

    - function: EnvAlternative
      target: configuration.alternatives[]
      appliesToKinds:
        - api
        - datastore
        - cache
      options:
        - function: Env
          target: configuration.env[]
          stringArgs:
            property: 0
            name: 1

How a profile uses extensions

The profile declares every extension required to interpret its vocabulary. Transitive dependencies are resolved by validators and tooling, but generated profiles should still declare the vocabulary they directly use.

Profile declaration and extension-owned fields

extensions:
  - https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml
  - https://runtimeconditions.io/extensions/env-configuration/v1alpha1/runtimeconditions.extension.yaml

conditions:
  - name: request-cache
    kind: cache              # common-integrations
    interface:
      type: key_value        # common-integrations
      engine: redis          # common-integrations field value
    configuration:           # env-configuration
      alternatives:
        - env:
            - property: url  # env-configuration field value
              name: REDIS_URL

Third-party extensions follow the same rules

The AWS Object Store extension is treated as a third-party example. It defines `aws.object_store`, `aws.s3`, S3-specific fields, and its own scoped `configuration` properties.

examples/extensions/aws-object-store/aws-object-store-v1alpha1.yaml source

metadata:
  id: https://aws.example.com/runtimeconditions/object-store/v1alpha1/runtimeconditions.extension.yaml

spec:
  kinds:
    - name: aws.object_store

  interfaceTypes:
    - name: aws.s3
      targetKind: aws.object_store

  conditionFields:
    - name: configuration
      appliesToKinds:
        - aws.object_store
      appliesToInterfaceTypes:
        - aws.s3

Extensions add vocabulary and validation to the core.