extensions.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Extensions | Runtime Conditions</title>
    <link rel="stylesheet" href="assets/styles.css" />
  </head>
  <body>
    <header class="site-header">
      <div class="header-inner">
        <a class="brand" href="index.html">Runtime Conditions</a>
        <nav class="top-links" aria-label="Top links">
          <a href="https://github.com/runtimeconditions/spec/blob/main/docs/sixth-draft.md" data-tip="Read the latest draft of the specification"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/><path d="M9 13h6"/><path d="M9 17h6"/></svg><span>Current Draft</span></a>
          <a href="https://github.com/runtimeconditions/rc-demos/blob/main/README.md" data-tip="Run Runtime Conditions end to end on your own machine"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="10"/><polygon points="10 8 16 12 10 16 10 8"/></svg><span>Run Demo</span></a>
          <a href="reference.html" data-tip="See where each part of this guide comes from in the source repositories"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 6l6-3 6 3 6-3v15l-6 3-6-3-6 3z"/><path d="M9 3v15"/><path d="M15 6v15"/></svg><span>Source Map</span></a>
          <a href="https://github.com/runtimeconditions" data-tip="Browse the Runtime Conditions repositories on GitHub"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg><span>GitHub</span></a>
          <a href="https://cloud-native.slack.com/archives/C0C0R4M65FZ" data-tip="Join the conversation on the CNCF Slack"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M4 9h16"/><path d="M4 15h16"/><path d="M10 3L8 21"/><path d="M16 3l-2 18"/></svg><span>Slack</span></a>
        </nav>
      </div>
    </header>

    <div class="guide-layout">
      <aside class="sidebar" aria-label="Guide chapters">
        <p class="sidebar-title">Reader Guide</p>
        <ol class="chapter-list">
          <li><a href="index.html"><span class="num">00</span><span>Start here</span></a></li>
          <li><a href="concepts.html"><span class="num">01</span><span>Core concepts</span></a></li>
          <li><a href="spec.html"><span class="num">02</span><span>Profile shape</span></a></li>
          <li><a href="developers.html"><span class="num">03</span><span>Code to profile</span></a></li>
          <li><a aria-current="page" href="extensions.html"><span class="num">04</span><span>Extensions</span></a></li>
          <li><a href="platform.html"><span class="num">05</span><span>Adapters</span></a></li>
          <li><a href="demo.html"><span class="num">06</span><span>Run the demo</span></a></li>
          <li><a href="reference.html"><span class="num">07</span><span>Reference</span></a></li>
        </ol>
      </aside>

      <main class="content">
        <p class="chapter-label">Chapter 4</p>
        <h1 class="page-title">Extensions add vocabulary and validation to the core.</h1>
        <p class="intro">
          The core profile shape is intentionally small. Extensions define the concrete words that make a profile useful: kinds, interface types, fields, field values, and JSON Schema validation.
        </p>

        <section class="section">
          <h2>What an extension owns</h2>
          <div class="table-wrap">
            <table>
              <thead>
                <tr><th>Extension Part</th><th>What It Does</th><th>Example</th></tr>
              </thead>
              <tbody>
                <tr><td>`dependencies`</td><td>References vocabulary owned by other extensions.</td><td>`https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml`</td></tr>
                <tr><td>`kinds`</td><td>Defines Condition categories.</td><td>`api`, `datastore`, `cache`</td></tr>
                <tr><td>`interfaceTypes`</td><td>Defines valid interface types for a kind.</td><td>`http` for `api`, `key_value` for `cache`</td></tr>
                <tr><td>`conditionFields`</td><td>Defines extension-owned fields on Conditions.</td><td>`configuration`</td></tr>
                <tr><td>`interfaceFields`</td><td>Defines extension-owned fields inside `interface`.</td><td>`interface.engine`, `interface.operations`</td></tr>
                <tr><td>`fieldValues`</td><td>Defines allowed values for extension-owned fields.</td><td>`redis`, `memcached`, `GET`, `POST`</td></tr>
                <tr><td>`schemas`</td><td>Defines machine-readable validation.</td><td>JSON Schema for HTTP API Conditions</td></tr>
              </tbody>
            </table>
          </div>
        </section>

        <section class="section">
          <h2>Choosing vocabulary keywords</h2>
          <p class="short">
            Each extension keyword answers a different authoring question. Use the smallest keyword that owns the vocabulary you are adding, then use schemas for shape.
          </p>
          <div class="table-wrap">
            <table>
              <thead>
                <tr><th>Author wants to</th><th>Use</th><th>Result</th></tr>
              </thead>
              <tbody>
                <tr><td>Add a Condition category</td><td>`kinds`</td><td>`kind: aws.object_store`</td></tr>
                <tr><td>Add an interface type for a kind</td><td>`interfaceTypes`</td><td>`interface.type: aws.s3`</td></tr>
                <tr><td>Add a top-level Condition field</td><td>`conditionFields`</td><td>`configuration`, `trust`, `access`</td></tr>
                <tr><td>Add a field inside `interface`</td><td>`interfaceFields`</td><td>`interface.engine`, `interface.bucketClass`</td></tr>
                <tr><td>Define portable value choices</td><td>`fieldValues`</td><td>`redis`, `standard`, `GET`</td></tr>
                <tr><td>Validate object shape</td><td>`schemas`</td><td>Required properties, arrays, conditional rules</td></tr>
              </tbody>
            </table>
          </div>
          <div class="example">
            <div class="example-title">Top-level field vs interface field</div>
            <pre><code>conditionFields:
  - name: configuration
    appliesToKinds:
      - cache
    appliesToInterfaceTypes:
      - key_value

interfaceFields:
  - name: engine
    targetKind: cache
    targetType: key_value</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>Field paths point to owned fields</h2>
          <p class="short">
            `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.
          </p>
          <div class="example">
            <div class="example-title">Interface path</div>
            <pre><code>interfaceFields:
  - name: bucketClass
    targetKind: aws.object_store
    targetType: aws.s3

fieldValues:
  - field: interface.bucketClass
    targetKind: aws.object_store
    targetType: aws.s3
    values:
      - standard
      - archive</code></pre>
          </div>
          <div class="example">
            <div class="example-title">Condition field path with array traversal</div>
            <pre><code>conditionFields:
  - name: configuration
    appliesToKinds:
      - cache
    appliesToInterfaceTypes:
      - key_value

fieldValues:
  - field: configuration.env[].property
    targetKind: cache
    targetType: key_value
    values:
      - url
      - hostname
      - port</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>First-party extension: Common Integrations</h2>
          <p class="short">
            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.
          </p>
          <div class="example">
            <div class="example-title">
              <span>common-integrations/common-integrations-v1alpha1.yaml</span>
              <a href="https://github.com/runtimeconditions/extensions/blob/main/common-integrations/common-integrations-v1alpha1.yaml">source</a>
            </div>
            <pre><code>metadata:
  id: https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml
  version: v1alpha1

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

  interfaceTypes:
    - name: http
      targetKind: api
    - name: key_value
      targetKind: cache</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>Field values make vocabulary deterministic</h2>
          <p class="short">
            The extension does not merely say an engine field may exist. It also owns the shared values that validators and adapters can rely on.
          </p>
          <div class="example">
            <div class="example-title">Cache engine values</div>
            <pre><code>fieldValues:
  - field: interface.engine
    targetKind: cache
    targetType: key_value
    values:
      - redis
      - memcached</code></pre>
          </div>
          <div class="example">
            <div class="example-title">HTTP method values</div>
            <pre><code>fieldValues:
  - field: interface.operations[].method
    targetKind: api
    targetType: http
    values:
      - GET
      - HEAD
      - POST
      - PUT
      - PATCH
      - DELETE
      - OPTIONS
      - TRACE</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>Extensions define JSON Schema validation</h2>
          <p class="short">
            Schema rules make extension validation portable. The validator can evaluate the profile without interpreting prose.
          </p>
          <div class="example">
            <div class="example-title">HTTP API schema excerpt</div>
            <pre><code>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</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>First-party extension: Environment Configuration</h2>
          <p class="short">
            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.
          </p>
          <div class="example">
            <div class="example-title">
              <span>env-configuration/env-configuration-v1alpha1.yaml</span>
              <a href="https://github.com/runtimeconditions/extensions/blob/main/env-configuration/env-configuration-v1alpha1.yaml">source</a>
            </div>
            <pre><code>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</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>Declaration packages follow ownership</h2>
          <p class="short">
            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.
          </p>
          <div class="example">
            <div class="example-title">Dual-import declaration code</div>
            <pre><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")),
)</code></pre>
          </div>
          <div class="example">
            <div class="example-title">Option-only binding manifest</div>
            <pre><code>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</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>How a profile uses extensions</h2>
          <p class="short">
            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.
          </p>
          <div class="example">
            <div class="example-title">Profile declaration and extension-owned fields</div>
            <pre><code>extensions:
  - https://runtimeconditions.io/extensions/common-integrations:v1alpha1
  - https://runtimeconditions.io/extensions/env-configuration:v1alpha1

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</code></pre>
          </div>
        </section>

        <section class="section">
          <h2>Third-party extensions follow the same rules</h2>
          <p class="short">
            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.
          </p>
          <div class="example">
            <div class="example-title">
              <span>examples/extensions/aws-object-store/aws-object-store-v1alpha1.yaml</span>
              <a href="https://github.com/runtimeconditions/spec/blob/main/examples/extensions/aws-object-store/aws-object-store-v1alpha1.yaml">source</a>
            </div>
            <pre><code>metadata:
  id: https://aws.example.com/runtimeconditions/object-store/v1alpha1/runtimeconditions.extension.yaml
  version: v1alpha1

spec:
  kinds:
    - name: aws.object_store

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

  conditionFields:
    - name: configuration
      appliesToKinds:
        - aws.object_store
      appliesToInterfaceTypes:
        - aws.s3</code></pre>
          </div>
        </section>

        <nav class="page-nav" aria-label="Page navigation">
          <a href="developers.html">Previous: Code to profile</a>
          <a href="platform.html">Next: Adapters</a>
        </nav>
      </main>
    </div>

    <footer class="footer">
      <div class="footer-inner">
        <span>Chapter 4 of 7</span>
        <a href="platform.html">Continue</a>
      </div>
    </footer>
    <script src="assets/syntax.js" defer></script>
  </body>
</html>