From 5ca38ff55eabfbaadaf7d68f131c10a7b883b4d6 Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Mon, 15 Jun 2026 05:33:25 -0400 Subject: [PATCH 1/4] adds spec draft for rfc Signed-off-by: Colin Lacy --- .../runtime-conditions-profile-spec-rfc.md | 672 ++++++++++++++++++ 1 file changed, 672 insertions(+) create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md new file mode 100644 index 000000000..80c8c3af7 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md @@ -0,0 +1,672 @@ +# Runtime Conditions Profile Specification (Draft) + +## Status + +**Draft — Request for Comments** + +This document is an early working draft of the Runtime Conditions Profile specification. + +It is intentionally not marked with a version and is being published solely to solicit early feedback from the community. + +This draft is expected to evolve significantly based on review and discussion before a stable version is tagged. + +## Request for Feedback + +The authors are particularly interested in feedback on: + +- Core Condition model structure +- Extension model design +- Validation behavior and layering +- Namespacing approach +- Overall scope boundaries + +Early architectural feedback is strongly encouraged. + +--- + +# 1. Purpose + +The Runtime Conditions Profile provides a **portable declaration of required external runtime capabilities** needed for an application workload to function successfully. + +These capabilities may include: + +- HTTP services +- Relational databases +- Caches +- Vendor-defined integration services + +The Runtime Conditions Profile: + +- **SHOULD be generated automatically when possible** +- **MAY be authored manually when automated generation is not feasible** +- **MUST remain valid regardless of generation method** +- **MUST remain implementation-neutral** +- **MUST remain infrastructure-agnostic** + +The profile defines **requirements**, not implementations. + +--- + +# 2. Scope + +This specification defines a portable format for describing the external capabilities that an application workload depends on in order to function properly. These dependencies represent integrations with services that exist outside the workload itself, such as HTTP APIs, databases, caches, and message systems. + +The Runtime Conditions Profile models each dependency as an independent requirement that describes the expected interface characteristics needed to interact with an external system. The specification focuses on describing what capabilities must be present, without describing how those capabilities are implemented or fulfilled. + +This specification is limited to externally satisfied integrations and does not attempt to describe internal execution behavior, infrastructure configuration, deployment topology, or platform-specific provisioning. It also does not require or depend on any upstream observation system, although such systems may be used to generate Runtime Conditions Profiles. + +--- + +# 3. Core Design Principles + +## 3.1 Declarative + +Profiles MUST be declarative documents describing what is required, not how to fulfill it. + +A Runtime Conditions Profile MUST be associated with a uniquely identifiable +workload and SHOULD correspond to a specific version of that workload. The profile version SHOULD align with the workload version. + +A Runtime Conditions Profile MUST describe exactly one workload identity +and MUST NOT represent multiple unrelated workloads within a single profile. + +## 3.2 Portable + +Profiles SHOULD be portable across environments and platforms when expressed using only core specification vocabulary. + +Profiles that use extension-defined vocabulary MAY introduce platform-specific or vendor-specific semantics. Such profiles remain portable to the extent that the required extensions are available. + +## 3.3 Implementation-Neutral + +Profiles MUST describe required capabilities without prescribing how those capabilities are implemented or provisioned. + +Core specification vocabulary MUST remain vendor-neutral and MUST NOT encode assumptions about specific infrastructure implementations. + +Vendor-specific or platform-specific identifiers MAY be used only when introduced through declared extensions. + +Profiles MUST NOT encode: + +- Infrastructure configuration details +- Deployment topology +- Resource sizing +- Geographic placement +- Provider-specific provisioning instructions + +## 3.4 Extensible + +Profiles MAY include extension-defined vocabulary to describe capabilities beyond those defined in the core specification. + +Profiles that use extension-defined vocabulary MUST identify the extensions on which that vocabulary depends. + +Use of extensions MUST NOT alter or redefine the meaning of core specification vocabulary. + +## 3.5 Deterministically Validatable + +Profiles MUST adhere to the structural and semantic validation rules defined by the core specification. + +Profiles that reference extension-defined vocabulary MUST also adhere to the validation rules defined by those extensions. + +--- + +# 4. Runtime Conditions Profile Structure + +A Runtime Conditions Profile defines a collection of independent runtime Conditions. + +Examples in this specification are expressed using YAML for readability. The data model defined by this specification is serialization-neutral and MAY be represented using YAML, JSON, or other compatible formats. + +## Top-Level Structure + +```yaml +## Top-Level Structure + +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile + +metadata: + name: example-profile + +workload: + uri: https://github.com/example-org/example-service + version: v1.2.3 + +extensions: + - core + - aws.runtime/v1alpha1 + +conditions: + - name: primary-db + kind: datastore + interface: + type: relational + + - name: payments-api + kind: service + interface: + type: http + operations: + - method: POST + path: /charge +``` + +--- + +# 5. Condition Model + +Each Condition represents an **independent required runtime dependency**. + +## Condition Fields + + +| Field | Required | Description | +| ----------- | -------- | ------------------------------------------ | +| `kind` | YES | Required capability classification | +| `interface` | YES | Interface definition required for matching | +| `name` | NO | Unique identifier within profile | + + +--- + +# 6. Core Condition Kinds + +The core specification defines a set of **capability classes**, referred to as **Kinds**, that represent common categories of externally satisfied runtime dependencies. + +Each Condition MUST declare exactly one `kind`. + +Kinds represent **broad capability families**, not specific technologies. + +The following core kinds are defined: + +- `service` — External service integrations such as APIs +- `datastore` — Persistent data storage systems +- `cache` — Volatile data storage optimized for fast access + +These kinds are intentionally broad so that multiple interaction models or implementation families can be expressed within the same capability class through the `interface` block. + +--- + +# 7. Interface Model + +Each Condition MUST define an `interface` block describing how the workload interacts with the declared capability. + +The `interface` block defines: + +- The **interaction model** +- The **matching characteristics** +- Any **additional details required for fulfillment matching** + +## Interface Structure + +```yaml +interface: + type: +``` + +The `type` field identifies the interaction model associated with the declared `kind`. + +Additional fields MAY be defined within `interface` depending on the declared `kind` and `interface.type`. + +Interface definitions are validated based on: + +- The declared `kind` +- The declared `interface.type` +- Core validation rules +- Extension validation rules, when applicable + +--- + +# 8. Core Interface Types + +This section describes the **structure and purpose** of core interface types. The set of currently supported interface types is defined in the validation section. + +--- + +## 8.1 Service Interface + +Service interfaces describe callable external services such as APIs. + +Service interfaces typically define: + +- Request methods +- Request paths +- Optional request schemas +- Optional response schemas + +Example: + +```yaml +kind: service +interface: + type: http + operations: + - method: POST + path: /charge + requestBodySchema: {} + responseSchema: {} +``` + +### Service Interface Fields + + +| Field | Required | Description | +| ------ | -------- | ---------------------------------------- | +| `type` | YES | Identifies the service interaction model | + + +Allowed values for `interface.type` are defined in Section 9.2. + +### Operation Fields + + +| Field | Required | Description | +| ------------------- | -------- | ------------------- | +| `method` | YES | HTTP method | +| `path` | YES | Request path | +| `requestBodySchema` | NO | Request body schema | +| `responseSchema` | NO | Response schema | + + +### Validation Expectations + +- `operations` MUST be non-empty +- `method` MUST be a valid HTTP method +- `path` MUST be a non-empty string +- Schema fields remain open-ended + +--- + +## 8.2 Datastore Interface + +Datastore interfaces describe persistent storage systems. + +Datastore interfaces identify the storage model used by the workload and MAY include additional matching details about the datastore engine. + +Example: + +```yaml +kind: datastore +interface: + type: relational + engine: postgres +``` + +### Datastore Interface Fields + + +| Field | Required | Description | +| -------- | -------- | ------------------------- | +| `type` | YES | Datastore interface type | +| `engine` | NO | Specific datastore engine | + + +If `engine` is provided, it MUST be valid for the declared datastore type. + +Allowed values for `interface.type` and `engine` are defined in Section 9.2. + +--- + +## 8.3 Cache Interface + +Cache interfaces describe volatile key/value storage systems. + +Example: + +```yaml +kind: cache +interface: + type: key_value + engine: redis +``` + +### Cache Interface Fields + + +| Field | Required | Description | +| -------- | -------- | ----------------------- | +| `type` | YES | Cache interface type | +| `engine` | NO | Specific caching engine | + + +If `engine` is provided, it MUST be valid for the declared cache type. + +Allowed values for `interface.type` and `engine` are defined in Section 9.2. + +--- + +# 9. Core Validation Rules + +Validation ensures that Conditions are structurally correct and semantically consistent. + +Validation occurs in multiple phases. + +--- + +## 9.1 Structural Validation + +A Condition is invalid if: + +- `kind` is missing +- `interface` is missing +- `interface.type` is missing + +If a `name` field is provided, it MUST be unique within the profile. + +--- + +## 9.2 Kind-to-Interface Type Validation + +Each `kind` supports a defined set of valid `interface.type` values. + +### Service + +Allowed interface types: + +- `http` + +Additional validation rules: + +- `operations` MUST be present +- `operations` MUST NOT be empty + +Allowed HTTP Methods: + +- GET +- HEAD +- POST +- PUT +- PATCH +- DELETE +- OPTIONS +- TRACE + +--- + +### Datastore + +Allowed interface types: + +- `relational` +- `document` + +Allowed `engine` values for `type: relational`: + +- `postgres` +- `mysql` +- `mariadb` +- `sqlserver` +- `oracle` +- `sqlite` + +Allowed `engine` values for `type: document`: + +- `mongodb` +- `couchbase` + +Additional validation rules: + +- `engine` is OPTIONAL +- If `engine` is present, it MUST be valid for the declared datastore type + +--- + +### Cache + +Allowed interface types: + +- `redis` +- `memcached` + +--- + +## 9.3 Invalid Condition Examples + +Invalid datastore engine for relational type: + +```yaml +kind: datastore +interface: + type: relational + engine: mongodb +``` + +Invalid interface type for cache: + +```yaml +kind: cache +interface: + type: relational +``` + +Invalid service definition: + +```yaml +kind: service +interface: + type: http + operations: [] +``` + +--- + +# 10. Extension Model + +The Runtime Conditions Profile supports extension-defined vocabulary. + +Extensions allow: + +- New kinds +- New interface types +- New interface fields +- Additional validation rules +- Additional allowed values for existing fields where semantically compatible + +Extensions MUST NOT redefine core semantics incompatibly. + +--- + +# 11. Extension Declaration + +Profiles that reference extension-defined vocabulary MUST identify those extensions. + +```yaml +extensions: + - core + - aws.runtime/v1alpha1 + - redis.compat/v1 +``` + +--- + +# 12. Extension Definition Structure + +Extensions are defined as independent artifacts. + +```yaml +apiVersion: runtimeconditions.io/v1alpha1 +kind: ValidationExtensionDefinition + +metadata: + name: aws.runtime + version: v1alpha1 + +spec: + + kinds: + - name: aws.object_store + + interfaceTypes: + - name: object_store + + typeExtensions: + - targetKind: cache + addTypes: + - valkey + + validationRules: + - id: cache-valkey + appliesToKind: cache + rule: type in ["redis","memcached","valkey"] +``` + +--- + +# 13. Extension Capabilities + +Extensions MAY: + + +| Action | Description | +| ------------------ | ----------------------------------------- | +| Add Kind | Introduce new namespaced kind | +| Add Interface Type | Define new interface types | +| Add Fields | Extend interface schema | +| Add Rules | Add semantic validation | +| Add Allowed Values | Extend allowed values for existing fields | + + +--- + +# 14. Extension Compatibility Rules + +Extensions MUST: + +- Use namespaced identifiers where they introduce new vocabulary +- Preserve core semantics +- Not redefine core kinds incompatibly +- Not invalidate core-valid documents + +Extensions MAY add new allowed values for existing fields only where those values are semantically compatible with the core meaning of the declared `kind` and `interface.type`. + +--- + +# 15. Namespacing Requirements + +Extension-defined vocabulary MUST use namespaced identifiers to avoid collisions with core or other extension-defined elements. + +Namespacing applies to: + +- Extension-defined `kind` values +- Extension-defined `interface.type` values +- Extension-defined field names (when applicable) + +Namespacing typically uses a prefix that identifies the originating organization or vendor. + +Examples of valid namespaced identifiers: + +```yaml +kind: aws.object_store +interface: + type: aws.s3 +``` + +```yaml +kind: service +interface: + type: acme.soap +``` + +Values defined within existing fields, such as `engine`, do not require namespacing unless necessary to prevent +collisions. + +--- + +# 16. Unknown Extension Handling + +Profiles MAY reference extension-defined vocabulary through the `extensions` declaration. + +If a profile references extension-defined vocabulary that cannot be resolved through its declared extensions, the profile MUST be considered invalid. + +This includes cases where: + +- A `kind` value is not defined in the core specification or in any declared extension +- An `interface.type` value is not defined in the core specification or in any declared extension +- A field defined by an extension is used without the corresponding extension being declared +- A declared extension cannot be located or resolved during validation + +Validation systems MUST reject Conditions that rely on unknown or unresolved extension-defined vocabulary. + +--- + +# 17. Validation Layers + +Validation occurs in the following order: + +1. Core structural validation +2. Core semantic validation +3. Extension resolution +4. Extension validation + +--- + +# 18. Example: Core-Only Profile + +```yaml +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile + +metadata: + name: checkout-service + +workload: + uri: https://github.com/example-org/checkout-service + version: v1.2.3 + +extensions: + - core + +conditions: + + - kind: datastore + interface: + type: relational + engine: postgres + + - kind: cache + interface: + type: redis + + - kind: service + interface: + type: http + operations: + - method: POST + path: /charge +``` + +--- + +# 19. Example: AWS Extension Profile + +```yaml +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile + +metadata: + name: storage-enabled + +workload: + uri: https://github.com/example-org/storage-service + version: v1.4.0 + +extensions: + - core + - aws.runtime/v1alpha1 + +conditions: + + - kind: aws.object_store + interface: + type: aws.s3 +``` + +--- + +# 20. Summary + +The Runtime Conditions Profile defines: + +- A portable dependency declaration format +- A structured interface typing model +- Deterministic validation behavior +- A declarative extension mechanism +- Vendor-neutral core semantics + +This provides a foundation for reliable downstream capability matching while preserving ecosystem flexibility. \ No newline at end of file From 8d05f1cb8ed27c6e94abf187c3b02d7dff74da83 Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Mon, 15 Jun 2026 06:27:59 -0400 Subject: [PATCH 2/4] addressed first round of feedback Signed-off-by: Colin Lacy --- .../runtime-conditions-profile-spec-rfc.md | 187 +++++++++++++++--- 1 file changed, 156 insertions(+), 31 deletions(-) diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md index 80c8c3af7..d649adb95 100644 --- a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md @@ -139,7 +139,7 @@ conditions: type: relational - name: payments-api - kind: service + kind: api interface: type: http operations: @@ -156,13 +156,22 @@ Each Condition represents an **independent required runtime dependency**. ## Condition Fields -| Field | Required | Description | -| ----------- | -------- | ------------------------------------------ | -| `kind` | YES | Required capability classification | -| `interface` | YES | Interface definition required for matching | -| `name` | NO | Unique identifier within profile | +| Field | Required | Description | +| ----------- | -------- | ------------------------------------------------- | +| `kind` | YES | Required capability classification | +| `interface` | YES | Interface definition required for matching | +| `name` | NO | Unique identifier within profile | +| `optional` | NO | Whether the Condition is optional. Defaults to `false` | +## Optional Conditions + +The `optional` field is a boolean that indicates whether a Condition is optional. + +When `optional` is omitted, it MUST be understood as `false`, meaning the Condition is required. It MAY be defined explicitly, but only setting `optional: true` changes downstream behavior. + +The logic for determining what makes a Condition optional is beyond the scope of this specification. It is the responsibility of both the developer and the platform team to decide how optional integration Conditions are handled. + --- # 6. Core Condition Kinds @@ -175,7 +184,7 @@ Kinds represent **broad capability families**, not specific technologies. The following core kinds are defined: -- `service` — External service integrations such as APIs +- `api` — External service integrations such as APIs - `datastore` — Persistent data storage systems - `cache` — Volatile data storage optimized for fast access @@ -219,40 +228,102 @@ This section describes the **structure and purpose** of core interface types. Th --- -## 8.1 Service Interface +## 8.1 API Interface -Service interfaces describe callable external services such as APIs. +API interfaces describe callable external services such as APIs. -Service interfaces typically define: +API interfaces typically define: - Request methods - Request paths - Optional request schemas - Optional response schemas +- An optional reference to an external API specification document Example: ```yaml -kind: service +kind: api interface: type: http + spec: + format: openapi + uri: https://github.com/example-org/example-service/openapi.yaml + version: ^1.2.0 operations: - method: POST path: /charge - requestBodySchema: {} - responseSchema: {} + requestBodySchema: + amount: integer + currency: string + responseSchema: + id: string + status: string ``` -### Service Interface Fields +### API Interface Fields -| Field | Required | Description | -| ------ | -------- | ---------------------------------------- | -| `type` | YES | Identifies the service interaction model | +| Field | Required | Description | +| ------------ | -------- | --------------------------------------------------- | +| `type` | YES | Identifies the API interaction model | +| `spec` | NO | Reference to an external API specification document | +| `operations` | NO | Explicit list of operations the workload depends on | Allowed values for `interface.type` are defined in Section 9.2. +At least one of `spec` or `operations` MUST be present. Both MAY be declared together. When both are present and disagree, the `operations` declaration takes precedence over `spec`. + +### API Specification Fields + +The `spec` block references an external API specification document describing the API the workload integrates with. + +```yaml +spec: + format: openapi + uri: https://github.com/example-org/example-service/openapi.yaml + version: ^1.2.0 +``` + + +| Field | Required | Description | +| --------- | -------- | ------------------------------------------------------ | +| `format` | YES | API specification format. Only `openapi` is currently supported | +| `uri` | YES | Location of the external specification document | +| `version` | NO | Required version of the referenced document, as an exact version or version constraint | + + +Only the OpenAPI specification is currently supported. Other API specification formats exist and MAY be supported in future versions. + +### Version Constraint Syntax + +`interface.spec.version` declares which version of the referenced specification document the workload requires. It accepts either an exact version or a version constraint expression, using the operators commonly found in dependency manifests such as `package.json`. + +Versions MUST follow Semantic Versioning, expressed as `MAJOR.MINOR.PATCH`. + +The following constraint operators are supported: + + +| Syntax | Name | Meaning | +| ---------- | ------------------- | ------------------------------------------------ | +| `1.2.3` | Exact | Matches only `1.2.3` | +| `=1.2.3` | Exact | Equivalent to `1.2.3` | +| `>1.2.3` | Greater than | Matches any version higher than `1.2.3` | +| `>=1.2.3` | Minimum | Matches `1.2.3` and any higher version | +| `<1.2.3` | Less than | Matches any version lower than `1.2.3` | +| `<=1.2.3` | Maximum | Matches `1.2.3` and any lower version | +| `^1.2.3` | Compatible (caret) | Matches `>=1.2.3` and `<2.0.0` (no major change) | +| `~1.2.3` | Approximate (tilde) | Matches `>=1.2.3` and `<1.3.0` (no minor change) | + + +When `version` is omitted, no version constraint is applied and any version of the referenced document is acceptable. + +Validation rules: + +- If `version` is present, it MUST be a valid Semantic Versioning version or a supported constraint expression +- Constraint operators MUST be drawn from the supported set above + ### Operation Fields @@ -260,16 +331,56 @@ Allowed values for `interface.type` are defined in Section 9.2. | ------------------- | -------- | ------------------- | | `method` | YES | HTTP method | | `path` | YES | Request path | -| `requestBodySchema` | NO | Request body schema | -| `responseSchema` | NO | Response schema | +| `requestBodySchema` | NO | Minimum required request body fields and their types | +| `responseSchema` | NO | Minimum required response fields and their types | + + +### Schema Fields +`requestBodySchema` and `responseSchema` describe the data structures an operation depends on. Each is expressed as a map whose keys are field names and whose values declare the JSON Schema type of each field. + +The declared fields represent the **minimum set of fields that MUST be present** in the external API. The external service MAY expose additional fields beyond those declared; only the declared fields participate in matching. + +Because the structure is expressed using field names and JSON Schema types rather than a specific API specification format, a Condition can be matched programmatically against any specification the external service publishes — including, but not limited to, the OpenAPI document referenced through `interface.spec`. + +A type declaration is one of: + +- A JSON Schema type keyword: `string`, `number`, `integer`, `boolean`, or `null` +- A nested object, declared by mapping field names to further type declarations +- An array, declared as a single-element list containing the element type declaration + +Example: + +```yaml +operations: + - method: POST + path: /charge + requestBodySchema: + amount: integer + currency: string + customer: + id: string + email: string + lineItems: + - sku: string + quantity: integer + responseSchema: + id: string + status: string + paid: boolean +``` ### Validation Expectations -- `operations` MUST be non-empty +- At least one of `spec` or `operations` MUST be present +- If `operations` is present, it MUST be non-empty - `method` MUST be a valid HTTP method - `path` MUST be a non-empty string -- Schema fields remain open-ended +- If present, `requestBodySchema` and `responseSchema` MUST be maps whose fields declare supported JSON Schema types +- Declared schema fields represent the minimum required set of fields and MAY be a subset of the fields exposed by the external API +- If `spec` is present, `spec.format` and `spec.uri` MUST be present +- `spec.format` MUST be `openapi` +- If `spec.version` is present, it MUST be a valid semantic version or supported version constraint expression --- @@ -355,7 +466,7 @@ If a `name` field is provided, it MUST be unique within the profile. Each `kind` supports a defined set of valid `interface.type` values. -### Service +### API Allowed interface types: @@ -363,8 +474,11 @@ Allowed interface types: Additional validation rules: -- `operations` MUST be present -- `operations` MUST NOT be empty +- At least one of `spec` or `operations` MUST be present +- If `operations` is present, it MUST NOT be empty +- If `spec` is present, `spec.format` and `spec.uri` MUST be present +- `spec.format` MUST be `openapi` +- If `spec.version` is present, it MUST be a valid semantic version or supported version constraint expression Allowed HTTP Methods: @@ -411,9 +525,18 @@ Additional validation rules: Allowed interface types: +- `key_value` + +Allowed `engine` values for `type: key_value`: + - `redis` - `memcached` +Additional validation rules: + +- `engine` is OPTIONAL +- If `engine` is present, it MUST be valid for the declared cache type + --- ## 9.3 Invalid Condition Examples @@ -435,10 +558,10 @@ interface: type: relational ``` -Invalid service definition: +Invalid api definition: ```yaml -kind: service +kind: api interface: type: http operations: [] @@ -497,13 +620,14 @@ spec: typeExtensions: - targetKind: cache - addTypes: + targetType: key_value + addEngines: - valkey validationRules: - id: cache-valkey appliesToKind: cache - rule: type in ["redis","memcached","valkey"] + rule: engine in ["redis","memcached","valkey"] ``` --- @@ -558,7 +682,7 @@ interface: ``` ```yaml -kind: service +kind: api interface: type: acme.soap ``` @@ -621,9 +745,10 @@ conditions: - kind: cache interface: - type: redis + type: key_value + engine: redis - - kind: service + - kind: api interface: type: http operations: From 908b68ed68cd77385796c168edc89cc7a4455ce4 Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Sun, 21 Jun 2026 14:26:28 -0400 Subject: [PATCH 3/4] reduces verbosity Signed-off-by: Colin Lacy --- .../runtime-conditions-profile-spec-rfc.md | 1060 +++++++++-------- 1 file changed, 563 insertions(+), 497 deletions(-) diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md index d649adb95..12205c2b9 100644 --- a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md @@ -2,141 +2,104 @@ ## Status -**Draft — Request for Comments** +**Draft - Request for Comments** -This document is an early working draft of the Runtime Conditions Profile specification. +This document defines the core Runtime Conditions Profile format. -It is intentionally not marked with a version and is being published solely to solicit early feedback from the community. +First-party extension drafts define common integration vocabulary separately: -This draft is expected to evolve significantly based on review and discussion before a stable version is tagged. - -## Request for Feedback - -The authors are particularly interested in feedback on: - -- Core Condition model structure -- Extension model design -- Validation behavior and layering -- Namespacing approach -- Overall scope boundaries - -Early architectural feedback is strongly encouraged. +- `https://runtimeconditions.io/extensions/common-integrations:v1alpha1` +- `https://runtimeconditions.io/extensions/env-configuration:v1alpha1` --- # 1. Purpose -The Runtime Conditions Profile provides a **portable declaration of required external runtime capabilities** needed for an application workload to function successfully. - -These capabilities may include: - -- HTTP services -- Relational databases -- Caches -- Vendor-defined integration services - -The Runtime Conditions Profile: +A Runtime Conditions Profile declares the external runtime integrations required by one application workload. -- **SHOULD be generated automatically when possible** -- **MAY be authored manually when automated generation is not feasible** -- **MUST remain valid regardless of generation method** -- **MUST remain implementation-neutral** -- **MUST remain infrastructure-agnostic** - -The profile defines **requirements**, not implementations. +The profile describes requirements. It does not describe implementations, provisioning actions, deployment topology, credentials, secret values, or concrete target-environment values. --- # 2. Scope -This specification defines a portable format for describing the external capabilities that an application workload depends on in order to function properly. These dependencies represent integrations with services that exist outside the workload itself, such as HTTP APIs, databases, caches, and message systems. - -The Runtime Conditions Profile models each dependency as an independent requirement that describes the expected interface characteristics needed to interact with an external system. The specification focuses on describing what capabilities must be present, without describing how those capabilities are implemented or fulfilled. - -This specification is limited to externally satisfied integrations and does not attempt to describe internal execution behavior, infrastructure configuration, deployment topology, or platform-specific provisioning. It also does not require or depend on any upstream observation system, although such systems may be used to generate Runtime Conditions Profiles. - ---- - -# 3. Core Design Principles - -## 3.1 Declarative +This specification defines: -Profiles MUST be declarative documents describing what is required, not how to fulfill it. +- The Runtime Conditions Profile document shape +- Workload identity fields +- Profile metadata labels +- The core Condition object shape +- Extension declaration and resolution rules +- Extension definition structure +- Validation layers +- Conformance requirements -A Runtime Conditions Profile MUST be associated with a uniquely identifiable -workload and SHOULD correspond to a specific version of that workload. The profile version SHOULD align with the workload version. +This specification does not define concrete Condition vocabulary. Condition kinds, interface types, field values, and type-specific fields are defined by extensions. -A Runtime Conditions Profile MUST describe exactly one workload identity -and MUST NOT represent multiple unrelated workloads within a single profile. +Concerns specifically beyond the scope of this specification include: -## 3.2 Portable - -Profiles SHOULD be portable across environments and platforms when expressed using only core specification vocabulary. - -Profiles that use extension-defined vocabulary MAY introduce platform-specific or vendor-specific semantics. Such profiles remain portable to the extent that the required extensions are available. - -## 3.3 Implementation-Neutral - -Profiles MUST describe required capabilities without prescribing how those capabilities are implemented or provisioned. - -Core specification vocabulary MUST remain vendor-neutral and MUST NOT encode assumptions about specific infrastructure implementations. - -Vendor-specific or platform-specific identifiers MAY be used only when introduced through declared extensions. - -Profiles MUST NOT encode: - -- Infrastructure configuration details +- Infrastructure provisioning behavior +- Platform-specific resource models - Deployment topology -- Resource sizing -- Geographic placement -- Provider-specific provisioning instructions - -## 3.4 Extensible - -Profiles MAY include extension-defined vocabulary to describe capabilities beyond those defined in the core specification. - -Profiles that use extension-defined vocabulary MUST identify the extensions on which that vocabulary depends. - -Use of extensions MUST NOT alter or redefine the meaning of core specification vocabulary. - -## 3.5 Deterministically Validatable +- Runtime configuration values +- Secret material +- Internal workload behavior +- Observability or code-analysis mechanisms used to generate a profile -Profiles MUST adhere to the structural and semantic validation rules defined by the core specification. +--- -Profiles that reference extension-defined vocabulary MUST also adhere to the validation rules defined by those extensions. +# 3. Profile Document ---- +Profiles MAY be serialized as YAML or JSON. -# 4. Runtime Conditions Profile Structure +Serialized profiles are invalid if: -A Runtime Conditions Profile defines a collection of independent runtime Conditions. +- A mapping contains duplicate keys +- A required field is missing +- A required field is present with `null` +- A field has a type other than the type defined by this specification -Examples in this specification are expressed using YAML for readability. The data model defined by this specification is serialization-neutral and MAY be represented using YAML, JSON, or other compatible formats. +Optional fields SHOULD be omitted when unused. -## Top-Level Structure +## 3.1 Complete Profile Example ```yaml -## Top-Level Structure - apiVersion: runtimeconditions.io/v1alpha1 kind: RuntimeConditionsProfile metadata: - name: example-profile + name: checkout-service + labels: + owner.example.com/team: payments + lifecycle.example.com/stage: production workload: - uri: https://github.com/example-org/example-service + uri: https://github.com/example-org/checkout-service version: v1.2.3 extensions: - - core - - aws.runtime/v1alpha1 + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 + - https://runtimeconditions.io/extensions/env-configuration:v1alpha1 conditions: - name: primary-db kind: datastore interface: type: relational + engine: postgres + configuration: + env: + - property: hostname + name: POSTGRES_HOST + - property: port + name: POSTGRES_PORT + - property: database + name: POSTGRES_DATABASE + - property: username + name: POSTGRES_USERNAME + - property: password + name: POSTGRES_PASSWORD + sensitive: true - name: payments-api kind: api @@ -145,582 +108,655 @@ conditions: operations: - method: POST path: /charge + configuration: + env: + - property: baseUrl + name: PAYMENTS_API_URL + - property: token + name: PAYMENTS_API_TOKEN + sensitive: true ``` ---- +## 3.2 Top-Level Fields -# 5. Condition Model +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `apiVersion` | string | YES | Runtime Conditions Profile API version | +| `kind` | string | YES | Document kind | +| `metadata` | object | YES | Profile metadata | +| `workload` | object | YES | Workload identity | +| `extensions` | array | YES | Extension identifiers required by the profile | +| `conditions` | array | YES | Runtime Conditions declared by the workload | -Each Condition represents an **independent required runtime dependency**. +`apiVersion` MUST be: -## Condition Fields +```text +runtimeconditions.io/v1alpha1 +``` +`kind` MUST be: -| Field | Required | Description | -| ----------- | -------- | ------------------------------------------------- | -| `kind` | YES | Required capability classification | -| `interface` | YES | Interface definition required for matching | -| `name` | NO | Unique identifier within profile | -| `optional` | NO | Whether the Condition is optional. Defaults to `false` | +```text +RuntimeConditionsProfile +``` +`extensions` MAY be empty if and only if the profile uses no extension-defined vocabulary. -## Optional Conditions +`conditions` MAY be empty if and only if the profile is intended to explicitly declare that the workload has no external runtime integration requirements. -The `optional` field is a boolean that indicates whether a Condition is optional. +## 3.3 Metadata -When `optional` is omitted, it MUST be understood as `false`, meaning the Condition is required. It MAY be defined explicitly, but only setting `optional: true` changes downstream behavior. +```yaml +metadata: + name: checkout-service + labels: + owner.example.com/team: payments + lifecycle.example.com/stage: production +``` -The logic for determining what makes a Condition optional is beyond the scope of this specification. It is the responsibility of both the developer and the platform team to decide how optional integration Conditions are handled. +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `name` | string | YES | Human-readable profile name | +| `labels` | object | NO | Machine-readable profile and workload classification labels | ---- +`metadata.name` MUST be a non-empty string. -# 6. Core Condition Kinds +`metadata.labels`, when present, MUST be a string-to-string mapping. -The core specification defines a set of **capability classes**, referred to as **Kinds**, that represent common categories of externally satisfied runtime dependencies. +Label keys MUST be non-empty strings. -Each Condition MUST declare exactly one `kind`. +Label values MUST be strings. -Kinds represent **broad capability families**, not specific technologies. +Label keys SHOULD be namespaced: -The following core kinds are defined: +```text +/ +``` -- `api` — External service integrations such as APIs -- `datastore` — Persistent data storage systems -- `cache` — Volatile data storage optimized for fast access +Examples: -These kinds are intentionally broad so that multiple interaction models or implementation families can be expressed within the same capability class through the `interface` block. +- `compliance.example.com/hipaa` +- `owner.example.com/team` +- `lifecycle.example.com/stage` +- `risk.example.com/criticality` ---- +The `runtimeconditions.io/` label namespace is reserved for the Runtime Conditions core specification and first-party Runtime Conditions extensions. -# 7. Interface Model +Extensions MAY document label key conventions. Label keys are metadata. They are not Condition vocabulary and do not participate in extension resolution unless a future version of this specification defines otherwise. -Each Condition MUST define an `interface` block describing how the workload interacts with the declared capability. +Labels MAY be used for selection, filtering, policy, ownership, reporting, and lifecycle workflows. -The `interface` block defines: +Labels MUST NOT define runtime dependency requirements or change the meaning of Conditions. -- The **interaction model** -- The **matching characteristics** -- Any **additional details required for fulfillment matching** +Labels MUST NOT contain secrets, protected data, personal data, customer data, or concrete target-environment values. -## Interface Structure +## 3.4 Workload ```yaml -interface: - type: +workload: + uri: https://github.com/example-org/checkout-service + version: v1.2.3 ``` -The `type` field identifies the interaction model associated with the declared `kind`. - -Additional fields MAY be defined within `interface` depending on the declared `kind` and `interface.type`. - -Interface definitions are validated based on: +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `uri` | string | YES | Stable workload identifier | +| `version` | string | NO | Workload version described by the profile | -- The declared `kind` -- The declared `interface.type` -- Core validation rules -- Extension validation rules, when applicable +`workload.uri` MUST be a non-empty string. ---- - -# 8. Core Interface Types +`workload.version`, when present, MUST be a non-empty string. -This section describes the **structure and purpose** of core interface types. The set of currently supported interface types is defined in the validation section. +A Runtime Conditions Profile MUST describe exactly one workload identity. --- -## 8.1 API Interface +# 4. Condition Model -API interfaces describe callable external services such as APIs. +Each Condition represents one external runtime dependency requirement. -API interfaces typically define: +## 4.1 Condition Fields -- Request methods -- Request paths -- Optional request schemas -- Optional response schemas -- An optional reference to an external API specification document +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `name` | string | NO | Unique Condition name within the profile | +| `optional` | boolean | NO | Whether the Condition is optional. Defaults to `false` | +| `kind` | string | YES | Extension-defined integration classification | +| `interface` | object | YES | Workload-facing interface requirement | -Example: +Condition shape: ```yaml -kind: api -interface: - type: http - spec: - format: openapi - uri: https://github.com/example-org/example-service/openapi.yaml - version: ^1.2.0 - operations: - - method: POST - path: /charge - requestBodySchema: - amount: integer - currency: string - responseSchema: - id: string - status: string +conditions: + - name: primary-db + optional: false + kind: datastore + interface: + type: relational ``` -### API Interface Fields - +`conditions[].name`, when present, MUST be a non-empty string and MUST be unique within the profile. -| Field | Required | Description | -| ------------ | -------- | --------------------------------------------------- | -| `type` | YES | Identifies the API interaction model | -| `spec` | NO | Reference to an external API specification document | -| `operations` | NO | Explicit list of operations the workload depends on | +`conditions[].optional`, when omitted, MUST be interpreted as `false`. +`conditions[].kind` MUST be a non-empty string and MUST be defined by exactly one resolved extension. -Allowed values for `interface.type` are defined in Section 9.2. +`conditions[].interface` MUST be an object. -At least one of `spec` or `operations` MUST be present. Both MAY be declared together. When both are present and disagree, the `operations` declaration takes precedence over `spec`. - -### API Specification Fields - -The `spec` block references an external API specification document describing the API the workload integrates with. - -```yaml -spec: - format: openapi - uri: https://github.com/example-org/example-service/openapi.yaml - version: ^1.2.0 -``` +Extensions MAY define additional Condition fields. +## 4.2 Interface Fields -| Field | Required | Description | -| --------- | -------- | ------------------------------------------------------ | -| `format` | YES | API specification format. Only `openapi` is currently supported | -| `uri` | YES | Location of the external specification document | -| `version` | NO | Required version of the referenced document, as an exact version or version constraint | +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `type` | string | YES | Extension-defined interface type for the declared `kind` | +`conditions[].interface.type` MUST be a non-empty string and MUST be defined by exactly one resolved extension for the declared `kind`. -Only the OpenAPI specification is currently supported. Other API specification formats exist and MAY be supported in future versions. +Extensions MAY define additional `interface` fields. -### Version Constraint Syntax +--- -`interface.spec.version` declares which version of the referenced specification document the workload requires. It accepts either an exact version or a version constraint expression, using the operators commonly found in dependency manifests such as `package.json`. +# 5. Extensions -Versions MUST follow Semantic Versioning, expressed as `MAJOR.MINOR.PATCH`. +Profiles that use extension-defined vocabulary MUST declare the required extensions. -The following constraint operators are supported: +First-party extensions are extensions. They are not core vocabulary and are not implicit. +Implementations MAY bundle support for first-party extensions, but generated profiles MUST still declare the vocabulary they use. -| Syntax | Name | Meaning | -| ---------- | ------------------- | ------------------------------------------------ | -| `1.2.3` | Exact | Matches only `1.2.3` | -| `=1.2.3` | Exact | Equivalent to `1.2.3` | -| `>1.2.3` | Greater than | Matches any version higher than `1.2.3` | -| `>=1.2.3` | Minimum | Matches `1.2.3` and any higher version | -| `<1.2.3` | Less than | Matches any version lower than `1.2.3` | -| `<=1.2.3` | Maximum | Matches `1.2.3` and any lower version | -| `^1.2.3` | Compatible (caret) | Matches `>=1.2.3` and `<2.0.0` (no major change) | -| `~1.2.3` | Approximate (tilde) | Matches `>=1.2.3` and `<1.3.0` (no minor change) | +## 5.1 Extension Identifiers +Extension identifiers MUST have this form: -When `version` is omitted, no version constraint is applied and any version of the referenced document is acceptable. +```text +: +``` -Validation rules: +The version delimiter is the final colon in the identifier. The extension URI is everything before that delimiter. The version is everything after that delimiter. -- If `version` is present, it MUST be a valid Semantic Versioning version or a supported constraint expression -- Constraint operators MUST be drawn from the supported set above +The extension URI MUST be an absolute HTTP or HTTPS URI. -### Operation Fields +The version MUST be a non-empty string. +This specification does not define the syntax or semantics of extension versions. Version interpretation is defined by the extension author and the Adapter. -| Field | Required | Description | -| ------------------- | -------- | ------------------- | -| `method` | YES | HTTP method | -| `path` | YES | Request path | -| `requestBodySchema` | NO | Minimum required request body fields and their types | -| `responseSchema` | NO | Minimum required response fields and their types | +Examples: +- `https://runtimeconditions.io/extensions/common-integrations:v1alpha1` +- `https://runtimeconditions.io/extensions/env-configuration:v1alpha1` +- `https://extensions.example.com/runtimeconditions/aws-object-store:2026.06.0` -### Schema Fields +Extension identifiers are case-sensitive. -`requestBodySchema` and `responseSchema` describe the data structures an operation depends on. Each is expressed as a map whose keys are field names and whose values declare the JSON Schema type of each field. +## 5.2 Extension Declarations -The declared fields represent the **minimum set of fields that MUST be present** in the external API. The external service MAY expose additional fields beyond those declared; only the declared fields participate in matching. +```yaml +extensions: + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 + - https://runtimeconditions.io/extensions/env-configuration:v1alpha1 +``` -Because the structure is expressed using field names and JSON Schema types rather than a specific API specification format, a Condition can be matched programmatically against any specification the external service publishes — including, but not limited to, the OpenAPI document referenced through `interface.spec`. +The `extensions` array MUST NOT contain duplicate extension identifiers. -A type declaration is one of: +Each `extensions` item MUST be a valid extension identifier. -- A JSON Schema type keyword: `string`, `number`, `integer`, `boolean`, or `null` -- A nested object, declared by mapping field names to further type declarations -- An array, declared as a single-element list containing the element type declaration +Declared extensions MAY depend on other extensions. -Example: +Declared extensions and transitive dependencies form the resolved extension set. -```yaml -operations: - - method: POST - path: /charge - requestBodySchema: - amount: integer - currency: string - customer: - id: string - email: string - lineItems: - - sku: string - quantity: integer - responseSchema: - id: string - status: string - paid: boolean -``` +Dependency resolution MUST be deterministic and MUST NOT depend on declaration order. -### Validation Expectations +A profile is invalid if: -- At least one of `spec` or `operations` MUST be present -- If `operations` is present, it MUST be non-empty -- `method` MUST be a valid HTTP method -- `path` MUST be a non-empty string -- If present, `requestBodySchema` and `responseSchema` MUST be maps whose fields declare supported JSON Schema types -- Declared schema fields represent the minimum required set of fields and MAY be a subset of the fields exposed by the external API -- If `spec` is present, `spec.format` and `spec.uri` MUST be present -- `spec.format` MUST be `openapi` -- If `spec.version` is present, it MUST be a valid semantic version or supported version constraint expression +- A declared extension cannot be resolved +- A transitive dependency cannot be resolved +- Extension dependency resolution contains a cycle +- The resolved extension set contains a vocabulary definition conflict --- -## 8.2 Datastore Interface +# 6. Extension Definitions -Datastore interfaces describe persistent storage systems. - -Datastore interfaces identify the storage model used by the workload and MAY include additional matching details about the datastore engine. +Extensions are defined as independent artifacts. -Example: +## 6.1 Extension Definition Fields ```yaml -kind: datastore -interface: - type: relational - engine: postgres -``` - -### Datastore Interface Fields - +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition -| Field | Required | Description | -| -------- | -------- | ------------------------- | -| `type` | YES | Datastore interface type | -| `engine` | NO | Specific datastore engine | +metadata: + uri: https://runtimeconditions.io/extensions/common-integrations + version: v1alpha1 +spec: + kinds: [] +``` -If `engine` is provided, it MUST be valid for the declared datastore type. +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `apiVersion` | string | YES | Runtime Conditions API version | +| `kind` | string | YES | MUST be `RuntimeConditionsExtensionDefinition` | +| `metadata` | object | YES | Extension identity | +| `spec` | object | YES | Extension vocabulary, dependencies, and validation schemas | -Allowed values for `interface.type` and `engine` are defined in Section 9.2. +`metadata.uri` MUST identify the extension URI and MUST be an absolute HTTP or HTTPS URI. ---- +`metadata.version` MUST identify the extension version. -## 8.3 Cache Interface +`:` MUST be a valid extension identifier. -Cache interfaces describe volatile key/value storage systems. +## 6.2 Extension Spec Fields -Example: +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `dependencies` | array | NO | Exact extension identifiers required by this extension | +| `kinds` | array | NO | Condition kinds defined by this extension | +| `interfaceTypes` | array | NO | Interface types defined by this extension | +| `conditionFields` | array | NO | Condition-level fields defined by this extension | +| `interfaceFields` | array | NO | Interface-level fields defined by this extension | +| `fieldValues` | array | NO | Field values defined by this extension | +| `schemas` | array | NO | JSON Schema validation schemas defined by this extension | -```yaml -kind: cache -interface: - type: key_value - engine: redis -``` - -### Cache Interface Fields +An extension MUST define at least one vocabulary item or validation schema. +Each `dependencies` item MUST be an exact extension identifier. -| Field | Required | Description | -| -------- | -------- | ----------------------- | -| `type` | YES | Cache interface type | -| `engine` | NO | Specific caching engine | +## 6.3 Vocabulary Definition Fields +Each `kinds` entry MUST include: -If `engine` is provided, it MUST be valid for the declared cache type. +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `name` | string | YES | Condition kind defined by the extension | -Allowed values for `interface.type` and `engine` are defined in Section 9.2. +Each `interfaceTypes` entry MUST include: ---- +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `name` | string | YES | Interface type defined by the extension | +| `targetKind` | string | YES | Condition kind for which the interface type is valid | -# 9. Core Validation Rules +Each `conditionFields` entry MUST include: -Validation ensures that Conditions are structurally correct and semantically consistent. +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `name` | string | YES | Condition-level field defined by the extension | +| `appliesToKinds` | array | NO | Kinds to which the field applies | +| `appliesToInterfaceTypes` | array | NO | Interface types to which the field applies | +| `appliesToAllKinds` | boolean | NO | Whether the field may apply to all Conditions. Defaults to `false` | -Validation occurs in multiple phases. +Each `conditionFields` entry MUST declare either `appliesToKinds` or `appliesToAllKinds: true`. ---- +Each `interfaceFields` entry MUST include: -## 9.1 Structural Validation +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `name` | string | YES | Interface-level field defined by the extension | +| `targetKind` | string | YES | Condition kind for which the field is valid | +| `targetType` | string | YES | Interface type for which the field is valid | -A Condition is invalid if: +Each `fieldValues` entry MUST include: -- `kind` is missing -- `interface` is missing -- `interface.type` is missing +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `field` | string | YES | Field path whose values are being defined | +| `targetKind` | string | YES | Condition kind scope | +| `targetType` | string | NO | Interface type scope | +| `values` | array | YES | Non-empty list of defined values | -If a `name` field is provided, it MUST be unique within the profile. +Each `fieldValues.values` entry MUST be unique within that `fieldValues` entry. ---- +Each `schemas` entry MUST include: -## 9.2 Kind-to-Interface Type Validation +| Field | Type | Required | Description | +| ----- | ---- | -------- | ----------- | +| `id` | string | YES | Schema identifier unique within the extension | +| `description` | string | YES | Human-readable summary | +| `appliesToKind` | string | NO | Condition kind scope | +| `appliesToInterfaceType` | string | NO | Interface type scope | +| `schema` | object | YES | JSON Schema 2020-12 schema | -Each `kind` supports a defined set of valid `interface.type` values. +Each `schemas[].schema` object MUST be a valid JSON Schema using the JSON Schema 2020-12 dialect. -### API +Each extension schema validates a Condition object after the profile has been converted to the JSON data model. -Allowed interface types: +A schema applies to a Condition when all declared scope fields match the Condition. Omitted scope fields do not restrict applicability. -- `http` +## 6.4 Extension Definition Example -Additional validation rules: +```yaml +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition -- At least one of `spec` or `operations` MUST be present -- If `operations` is present, it MUST NOT be empty -- If `spec` is present, `spec.format` and `spec.uri` MUST be present -- `spec.format` MUST be `openapi` -- If `spec.version` is present, it MUST be a valid semantic version or supported version constraint expression +metadata: + uri: https://aws.example.com/runtimeconditions/object-store + version: v1alpha1 -Allowed HTTP Methods: +spec: + kinds: + - name: aws.object_store -- GET -- HEAD -- POST -- PUT -- PATCH -- DELETE -- OPTIONS -- TRACE + interfaceTypes: + - name: aws.s3 + targetKind: aws.object_store + + interfaceFields: + - name: bucketClass + targetKind: aws.object_store + targetType: aws.s3 + + fieldValues: + - field: interface.bucketClass + targetKind: aws.object_store + targetType: aws.s3 + values: + - standard + - archive + + schemas: + - id: aws-s3-interface + appliesToKind: aws.object_store + appliesToInterfaceType: aws.s3 + description: Validates the aws.s3 interface shape. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: + - kind + - interface + properties: + kind: + const: aws.object_store + interface: + type: object + required: + - type + properties: + type: + const: aws.s3 + bucketClass: + enum: + - standard + - archive + additionalProperties: true +``` --- -### Datastore +# 7. Extension Vocabulary Rules -Allowed interface types: +Extensions MAY define: -- `relational` -- `document` +- New Condition kinds +- New interface types +- New Condition fields +- New interface fields +- New field values +- JSON Schema validation schemas -Allowed `engine` values for `type: relational`: +Extensions MUST NOT: -- `postgres` -- `mysql` -- `mariadb` -- `sqlserver` -- `oracle` -- `sqlite` +- Redefine core fields +- Change core field meaning +- Define additional top-level profile fields +- Define additional fields within `metadata` or `workload` +- Encode secrets or concrete target-environment values -Allowed `engine` values for `type: document`: +Core-reserved top-level fields: -- `mongodb` -- `couchbase` +- `apiVersion` +- `kind` +- `metadata` +- `workload` +- `extensions` +- `conditions` -Additional validation rules: +Core-reserved Condition fields: -- `engine` is OPTIONAL -- If `engine` is present, it MUST be valid for the declared datastore type +- `name` +- `optional` +- `kind` +- `interface` ---- +Core-reserved interface field: -### Cache +- `type` -Allowed interface types: +## 7.1 Vocabulary Definition Scope -- `key_value` +Vocabulary definition scope is determined by: -Allowed `engine` values for `type: key_value`: +- Vocabulary category +- Field path, for field values +- Target Condition `kind`, when applicable +- Target `interface.type`, when applicable -- `redis` -- `memcached` +A profile is invalid if the resolved extension set contains more than one definition for the same vocabulary item in the same scope. -Additional validation rules: +Two definitions conflict even when they are identical. -- `engine` is OPTIONAL -- If `engine` is present, it MUST be valid for the declared cache type +An extension that uses vocabulary defined by another extension MUST declare a dependency on that extension. It MUST NOT redefine that vocabulary in the same definition scope. ---- +An extension MAY define vocabulary with overlapping purpose when it uses a distinct name or definition scope. -## 9.3 Invalid Condition Examples +## 7.2 Namespacing -Invalid datastore engine for relational type: +Extension-defined vocabulary SHOULD use namespaced identifiers when the vocabulary is vendor-specific, platform-specific, experimental, or likely to conflict. -```yaml -kind: datastore -interface: - type: relational - engine: mongodb -``` +Namespacing applies to: -Invalid interface type for cache: +- `kind` values +- `interface.type` values +- Condition field names +- Interface field names +- Field values that are not intended to be shared vocabulary + +Examples: ```yaml -kind: cache +kind: aws.object_store interface: - type: relational + type: aws.s3 ``` -Invalid api definition: - ```yaml kind: api interface: - type: http - operations: [] + type: acme.soap ``` +Unqualified vocabulary MAY be used when it resolves to exactly one definition in the resolved extension set. + --- -# 10. Extension Model +# 8. Validation -The Runtime Conditions Profile supports extension-defined vocabulary. +Validation occurs in this order: -Extensions allow: +1. Core structural validation +2. Extension declaration resolution +3. Extension dependency resolution +4. Vocabulary definition and conflict validation +5. Extension JSON Schema validation -- New kinds -- New interface types -- New interface fields -- Additional validation rules -- Additional allowed values for existing fields where semantically compatible +## 8.1 Structural Validation -Extensions MUST NOT redefine core semantics incompatibly. +A profile is structurally invalid if: ---- +- `apiVersion` is missing or is not `runtimeconditions.io/v1alpha1` +- `kind` is missing or is not `RuntimeConditionsProfile` +- `metadata` is missing or is not an object +- `metadata.name` is missing or is not a non-empty string +- `metadata.labels` is present and is not a string-to-string mapping +- `workload` is missing or is not an object +- `workload.uri` is missing or is not a non-empty string +- `workload.version` is present and is not a non-empty string +- `extensions` is missing or is not an array +- `conditions` is missing or is not an array +- Any required field is present with `null` +- Any mapping contains duplicate keys -# 11. Extension Declaration +A Condition is structurally invalid if: -Profiles that reference extension-defined vocabulary MUST identify those extensions. +- It is not an object +- `kind` is missing or is not a non-empty string +- `interface` is missing or is not an object +- `interface.type` is missing or is not a non-empty string +- `name` is present and is not a non-empty string +- `optional` is present and is not a boolean -```yaml -extensions: - - core - - aws.runtime/v1alpha1 - - redis.compat/v1 -``` +Condition names, when present, MUST be unique within the profile. ---- +## 8.2 Vocabulary Validation -# 12. Extension Definition Structure +A profile is invalid if: -Extensions are defined as independent artifacts. +- A Condition `kind` is not defined by exactly one resolved extension +- An `interface.type` is not defined by exactly one resolved extension for the declared `kind` +- An extension-defined Condition field is not defined by exactly one resolved extension for its scope +- An extension-defined interface field is not defined by exactly one resolved extension for its scope +- An extension-defined field value is not defined by exactly one resolved extension for its scope +- Any resolved extension dependency is missing +- Resolved extensions contain a dependency cycle +- Resolved extensions contain a vocabulary definition conflict +- Any applicable extension JSON Schema validation fails -```yaml -apiVersion: runtimeconditions.io/v1alpha1 -kind: ValidationExtensionDefinition +## 8.3 Validity Levels -metadata: - name: aws.runtime - version: v1alpha1 +Validators SHOULD distinguish: -spec: +| Level | Description | +| ----- | ----------- | +| **Structural validity** | The document satisfies the core shape and type rules | +| **Extension-resolved validity** | All extensions resolve and all vocabulary has exactly one definition in scope | +| **Semantic validity** | The profile satisfies all applicable extension JSON Schema validations | - kinds: - - name: aws.object_store +A core-only profile with an empty `conditions` array can be structurally valid. - interfaceTypes: - - name: object_store - - typeExtensions: - - targetKind: cache - targetType: key_value - addEngines: - - valkey - - validationRules: - - id: cache-valkey - appliesToKind: cache - rule: engine in ["redis","memcached","valkey"] -``` +A profile with non-empty `conditions` is not extension-resolved valid unless every Condition kind, interface type, extension-defined field, and extension-defined value resolves to exactly one definition. + +## 8.4 Validator Diagnostics + +Validation errors SHOULD identify: + +- Error category +- Location within the profile +- Offending field or value +- Relevant extension, when applicable +- Expected valid type or vocabulary, when practical + +Suggested error categories: + +- `structural` +- `unknown-extension` +- `extension-dependency` +- `unresolved-vocabulary` +- `vocabulary-conflict` +- `semantic` --- -# 13. Extension Capabilities +# 9. Conformance -Extensions MAY: +## 9.1 Profile Conformance +A conforming profile MUST: -| Action | Description | -| ------------------ | ----------------------------------------- | -| Add Kind | Introduce new namespaced kind | -| Add Interface Type | Define new interface types | -| Add Fields | Extend interface schema | -| Add Rules | Add semantic validation | -| Add Allowed Values | Extend allowed values for existing fields | +- Satisfy core structural requirements +- Declare all extensions required to interpret its vocabulary +- Avoid unresolved vocabulary +- Avoid vocabulary definition conflicts +- Satisfy all semantic validation schemas for resolved extensions +- Avoid secret values and concrete target-environment values +## 9.2 Extension Conformance ---- +A conforming extension MUST: -# 14. Extension Compatibility Rules +- Use a valid extension identifier +- Provide a valid extension definition artifact +- Identify all vocabulary it defines +- Declare exact-version dependencies on vocabulary defined by other extensions +- Avoid redefining vocabulary defined by another resolved extension +- Respect core field placement and reserved-name rules +- Express semantic validation with JSON Schema 2020-12 schemas -Extensions MUST: +## 9.3 Generator Conformance -- Use namespaced identifiers where they introduce new vocabulary -- Preserve core semantics -- Not redefine core kinds incompatibly -- Not invalidate core-valid documents +A conforming generator MUST emit structurally valid profiles. -Extensions MAY add new allowed values for existing fields only where those values are semantically compatible with the core meaning of the declared `kind` and `interface.type`. +A conforming generator MUST NOT emit secret values or concrete target-environment values. ---- +A conforming generator SHOULD fail before emitting a profile with unresolved vocabulary, missing extensions, dependency errors, or known vocabulary conflicts. -# 15. Namespacing Requirements +## 9.4 Validator Conformance -Extension-defined vocabulary MUST use namespaced identifiers to avoid collisions with core or other extension-defined elements. +A conforming validator MUST implement the validation layers in Section 8. -Namespacing applies to: +A conforming validator MUST reject structurally invalid profiles, unresolved extensions, dependency cycles, vocabulary conflicts, unresolved vocabulary, and JSON Schema validation failures. -- Extension-defined `kind` values -- Extension-defined `interface.type` values -- Extension-defined field names (when applicable) +## 9.5 Adapter Conformance -Namespacing typically uses a prefix that identifies the originating organization or vendor. +An Adapter consumes a Runtime Conditions Profile for a target platform, catalog, policy system, or deployment workflow. -Examples of valid namespaced identifiers: +A conforming Adapter MUST locate declared extension definitions and transitive extension dependencies before interpreting extension-defined vocabulary. -```yaml -kind: aws.object_store -interface: - type: aws.s3 -``` +A conforming Adapter MUST NOT treat a structurally valid but extension-unresolved profile as semantically valid. -```yaml -kind: api -interface: - type: acme.soap -``` +A conforming Adapter MUST preserve the distinction between profile requirements and target-environment fulfillment choices. -Values defined within existing fields, such as `engine`, do not require namespacing unless necessary to prevent -collisions. +A conforming Adapter MAY map valid Conditions to platform resources, services, policies, configuration inputs, or deployment workflow steps. Such mappings are outside the profile data model. --- -# 16. Unknown Extension Handling +# 10. Examples + +## 10.1 Core-Only Structural Profile + +```yaml +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile + +metadata: + name: structural-profile + labels: + owner.example.com/team: platform -Profiles MAY reference extension-defined vocabulary through the `extensions` declaration. +workload: + uri: https://github.com/example-org/example-service + version: v1.2.3 -If a profile references extension-defined vocabulary that cannot be resolved through its declared extensions, the profile MUST be considered invalid. +extensions: [] -This includes cases where: +conditions: [] +``` -- A `kind` value is not defined in the core specification or in any declared extension -- An `interface.type` value is not defined in the core specification or in any declared extension -- A field defined by an extension is used without the corresponding extension being declared -- A declared extension cannot be located or resolved during validation +## 10.2 Unresolved Conditions -Validation systems MUST reject Conditions that rely on unknown or unresolved extension-defined vocabulary. +This profile is structurally valid but not extension-resolved valid. ---- +```yaml +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile -# 17. Validation Layers +metadata: + name: unresolved-profile -Validation occurs in the following order: +workload: + uri: https://github.com/example-org/example-service -1. Core structural validation -2. Core semantic validation -3. Extension resolution -4. Extension validation +extensions: [] ---- +conditions: + - name: primary-db + kind: relational-database + interface: + type: connection +``` -# 18. Example: Core-Only Profile +## 10.3 Extension-Backed Profile ```yaml apiVersion: runtimeconditions.io/v1alpha1 @@ -728,27 +764,26 @@ kind: RuntimeConditionsProfile metadata: name: checkout-service + labels: + owner.example.com/team: payments + lifecycle.example.com/stage: production workload: uri: https://github.com/example-org/checkout-service version: v1.2.3 extensions: - - core + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 conditions: - - - kind: datastore + - name: primary-db + kind: datastore interface: type: relational engine: postgres - - kind: cache - interface: - type: key_value - engine: redis - - - kind: api + - name: payments-api + kind: api interface: type: http operations: @@ -756,42 +791,73 @@ conditions: path: /charge ``` ---- - -# 19. Example: AWS Extension Profile +## 10.4 Extension-Backed Profile With Configuration ```yaml apiVersion: runtimeconditions.io/v1alpha1 kind: RuntimeConditionsProfile metadata: - name: storage-enabled + name: checkout-service + labels: + owner.example.com/team: payments workload: - uri: https://github.com/example-org/storage-service - version: v1.4.0 + uri: https://github.com/example-org/checkout-service + version: v1.2.3 extensions: - - core - - aws.runtime/v1alpha1 + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 + - https://runtimeconditions.io/extensions/env-configuration:v1alpha1 conditions: + - name: primary-db + kind: datastore + interface: + type: relational + engine: postgres + configuration: + env: + - property: hostname + name: POSTGRES_HOST + - property: port + name: POSTGRES_PORT + - property: database + name: POSTGRES_DATABASE + - property: username + name: POSTGRES_USERNAME + - property: password + name: POSTGRES_PASSWORD + sensitive: true + + - name: request-cache + kind: cache + interface: + type: key_value + engine: redis + configuration: + alternatives: + - env: + - property: url + name: REDIS_URL + - env: + - property: hostname + name: REDIS_HOST + - property: port + name: REDIS_PORT - - kind: aws.object_store + - name: payments-api + kind: api interface: - type: aws.s3 + type: http + operations: + - method: POST + path: /charge + configuration: + env: + - property: baseUrl + name: PAYMENTS_API_URL + - property: token + name: PAYMENTS_API_TOKEN + sensitive: true ``` - ---- - -# 20. Summary - -The Runtime Conditions Profile defines: - -- A portable dependency declaration format -- A structured interface typing model -- Deterministic validation behavior -- A declarative extension mechanism -- Vendor-neutral core semantics - -This provides a foundation for reliable downstream capability matching while preserving ecosystem flexibility. \ No newline at end of file From 48f70dd83e8024066256ceb7f08ceee9bcdccfd8 Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Sun, 21 Jun 2026 15:50:58 -0400 Subject: [PATCH 4/4] adds support documents and examples Signed-off-by: Colin Lacy --- .../README.md | 18 + .../examples/README.md | 6 + .../examples/checkout-service-profile.yaml | 74 ++++ .../examples/object-store-profile.yaml | 34 ++ .../extensions/README.md | 13 + .../common-integrations-v1alpha1.yaml | 254 +++++++++++++ .../env-configuration-v1alpha1.yaml | 351 ++++++++++++++++++ .../aws-object-store-v1alpha1.yaml | 118 ++++++ .../relationship-to-adjacent-work.md | 14 + .../security-and-privacy-considerations.md | 12 + ...ntime-conditions-profile-specification.md} | 0 .../README.md | 5 + 12 files changed, 899 insertions(+) create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/README.md create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/README.md create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/checkout-service-profile.yaml create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/object-store-profile.yaml create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/README.md create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/common-integrations-v1alpha1.yaml create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/env-configuration-v1alpha1.yaml create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/third-party-example/aws-object-store-v1alpha1.yaml create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/relationship-to-adjacent-work.md create mode 100644 tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/security-and-privacy-considerations.md rename tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/{runtime-conditions-profile-spec-rfc.md => 2-spec-draft-and-support-artifacts/runtime-conditions-profile-specification.md} (100%) diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/README.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/README.md new file mode 100644 index 000000000..8a48acaba --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/README.md @@ -0,0 +1,18 @@ +# Runtime Conditions Profile draft and support artifacts + +This directory contains the draft Runtime Conditions Profile Specification, and the minimum supporting artifacts needed to review it as a cohesive initiative. + +## Contents + +- `runtime-conditions-profile-specification.md` - core draft specification. +- `extensions/` - machine-readable extension definition files that define Condition vocabulary, allowed values, and validation schemas used by the examples. +- `examples/` - complete profile documents that show the core shape and extension usage. +- `review-notes/` - short non-normative notes for common review questions. + +## Review scope + +The core profile specification and extension definition shape are the main items for review. The first-party extension YAML files show how concrete vocabulary can be defined outside the core. The AWS object-store extension is intentionally illustrative: it demonstrates third-party extension mechanics, while clearly falling short of a full third-party implementation. + +Generators, platform adapters, and a working demo are intentionally not included here. They can be found at https://github.com/colinjlacy/runtime-conditions-profiles. + +For a guided walkthrough explaining the core concepts, see: https://colinjlacy.github.io/runtime-conditions-profiles/ diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/README.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/README.md new file mode 100644 index 000000000..55c2552af --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/README.md @@ -0,0 +1,6 @@ +# Profile examples + +These examples are complete Runtime Conditions Profile documents. + +- `checkout-service-profile.yaml` uses only the first-party Common Integrations and Env Configuration extensions. +- `object-store-profile.yaml` shows how a profile can use an illustrative third-party extension for provider-specific object storage vocabulary. diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/checkout-service-profile.yaml b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/checkout-service-profile.yaml new file mode 100644 index 000000000..074a2b365 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/checkout-service-profile.yaml @@ -0,0 +1,74 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile + +metadata: + name: checkout-service + labels: + owner.example.com/team: payments + lifecycle.example.com/stage: production + +workload: + uri: https://github.com/example-org/checkout-service + version: v1.2.3 + +extensions: + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 + - https://runtimeconditions.io/extensions/env-configuration:v1alpha1 + +conditions: + - name: primary-db + kind: datastore + interface: + type: relational + engine: postgres + configuration: + env: + - property: hostname + name: POSTGRES_HOST + - property: port + name: POSTGRES_PORT + - property: database + name: POSTGRES_DATABASE + - property: username + name: POSTGRES_USERNAME + - property: password + name: POSTGRES_PASSWORD + sensitive: true + + - name: request-cache + kind: cache + interface: + type: key_value + engine: redis + configuration: + alternatives: + - env: + - property: url + name: REDIS_URL + - env: + - property: hostname + name: REDIS_HOST + - property: port + name: REDIS_PORT + + - name: payments-api + kind: api + interface: + type: http + operations: + - method: POST + path: /charge + requestBodySchema: + amount: number + currency: string + paymentMethodToken: string + responseSchema: + chargeId: string + status: string + configuration: + env: + - property: baseUrl + name: PAYMENTS_API_URL + - property: token + name: PAYMENTS_API_TOKEN + sensitive: true diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/object-store-profile.yaml b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/object-store-profile.yaml new file mode 100644 index 000000000..936a909cd --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/examples/object-store-profile.yaml @@ -0,0 +1,34 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsProfile + +metadata: + name: audit-logger + labels: + owner.example.com/team: platform + +workload: + uri: https://github.com/example-org/audit-logger + version: v0.4.0 + +extensions: + - https://aws.example.com/runtimeconditions/object-store:v1alpha1 + +conditions: + - name: audit-log-store + kind: aws.object_store + interface: + type: aws.s3 + bucketClass: standard + configuration: + env: + - property: bucket + name: AUDIT_LOG_BUCKET + - property: region + name: AWS_REGION + - property: accessKeyId + name: AWS_ACCESS_KEY_ID + sensitive: true + - property: secretAccessKey + name: AWS_SECRET_ACCESS_KEY + sensitive: true + diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/README.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/README.md new file mode 100644 index 000000000..cbf38cab2 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/README.md @@ -0,0 +1,13 @@ +# Extension definitions + +Runtime Conditions Profiles have a small, extensible core. Concrete integration vocabulary is defined by extensions. + +This directory includes: + +- `first-party/common-integrations-v1alpha1.yaml` - vocabulary for common integration categories such as APIs, datastores, and caches. Intended to be supported upon release. +- `first-party/env-configuration-v1alpha1.yaml` - vocabulary for declaring workload-facing environment variable inputs. Intended to be supported upon release. +- `third-party-example/aws-object-store-v1alpha1.yaml` - illustrative third-party extension for an AWS S3-style object store condition. Intended as an example for third-party authorship. + +The first two files are the extension artifacts referenced by the complete examples. They are included so reviewers can see that condition kinds, interface types, fields, field values, and JSON Schema validation can be declared outside the core specification. + +The AWS file is intentionally provider-specific. It exists to show the expected third-party extension path: an extension can declare its own URI, depend on first-party extensions, define provider-specific vocabulary, and constrain that vocabulary using JSON Schema. diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/common-integrations-v1alpha1.yaml b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/common-integrations-v1alpha1.yaml new file mode 100644 index 000000000..7c7909d58 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/common-integrations-v1alpha1.yaml @@ -0,0 +1,254 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition + +metadata: + uri: https://runtimeconditions.io/extensions/common-integrations + version: v1alpha1 + +spec: + kinds: + - name: api + - name: datastore + - name: cache + + interfaceTypes: + - name: http + targetKind: api + - name: relational + targetKind: datastore + - name: document + targetKind: datastore + - name: key_value + targetKind: cache + + interfaceFields: + - name: spec + targetKind: api + targetType: http + - name: operations + targetKind: api + targetType: http + - name: engine + targetKind: datastore + targetType: relational + - name: engine + targetKind: datastore + targetType: document + - name: engine + targetKind: cache + targetType: key_value + + fieldValues: + - field: interface.spec.format + targetKind: api + targetType: http + values: + - openapi + - field: interface.operations[].method + targetKind: api + targetType: http + values: + - GET + - HEAD + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + - TRACE + - field: interface.engine + targetKind: datastore + targetType: relational + values: + - postgres + - mysql + - mariadb + - sqlserver + - oracle + - sqlite + - field: interface.engine + targetKind: datastore + targetType: document + values: + - mongodb + - couchbase + - field: interface.engine + targetKind: cache + targetType: key_value + values: + - redis + - memcached + + schemas: + - id: api-http-interface + appliesToKind: api + appliesToInterfaceType: http + description: Validates HTTP API integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: + - kind + - interface + properties: + kind: + const: api + interface: + type: object + required: + - type + properties: + type: + const: http + spec: + type: object + required: + - format + - uri + properties: + format: + const: openapi + uri: + type: string + minLength: 1 + version: + type: string + pattern: '^(?:=?[0-9]+\.[0-9]+\.[0-9]+|[<>]=?[0-9]+\.[0-9]+\.[0-9]+|\^[0-9]+\.[0-9]+\.[0-9]+|~[0-9]+\.[0-9]+\.[0-9]+)$' + additionalProperties: false + operations: + type: array + minItems: 1 + items: + type: object + required: + - method + - path + properties: + method: + enum: + - GET + - HEAD + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + - TRACE + path: + type: string + minLength: 1 + requestBodySchema: + $ref: '#/$defs/simpleSchema' + responseSchema: + $ref: '#/$defs/simpleSchema' + additionalProperties: false + anyOf: + - required: + - spec + - required: + - operations + additionalProperties: true + additionalProperties: true + $defs: + simpleSchema: + oneOf: + - type: string + enum: + - string + - number + - integer + - boolean + - "null" + - type: object + additionalProperties: + $ref: '#/$defs/simpleSchema' + - type: array + minItems: 1 + maxItems: 1 + items: + $ref: '#/$defs/simpleSchema' + + - id: datastore-relational-interface + appliesToKind: datastore + appliesToInterfaceType: relational + description: Validates relational datastore integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: + - kind + - interface + properties: + kind: + const: datastore + interface: + type: object + required: + - type + properties: + type: + const: relational + engine: + enum: + - postgres + - mysql + - mariadb + - sqlserver + - oracle + - sqlite + additionalProperties: true + additionalProperties: true + + - id: datastore-document-interface + appliesToKind: datastore + appliesToInterfaceType: document + description: Validates document datastore integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: + - kind + - interface + properties: + kind: + const: datastore + interface: + type: object + required: + - type + properties: + type: + const: document + engine: + enum: + - mongodb + - couchbase + additionalProperties: true + additionalProperties: true + + - id: cache-key-value-interface + appliesToKind: cache + appliesToInterfaceType: key_value + description: Validates key/value cache integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: + - kind + - interface + properties: + kind: + const: cache + interface: + type: object + required: + - type + properties: + type: + const: key_value + engine: + enum: + - redis + - memcached + additionalProperties: true + additionalProperties: true diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/env-configuration-v1alpha1.yaml b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/env-configuration-v1alpha1.yaml new file mode 100644 index 000000000..f4a45a4d9 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/first-party/env-configuration-v1alpha1.yaml @@ -0,0 +1,351 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition + +metadata: + uri: https://runtimeconditions.io/extensions/env-configuration + version: v1alpha1 + +spec: + dependencies: + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 + + conditionFields: + - name: configuration + appliesToAllKinds: true + + fieldValues: + - field: configuration.env[].property + targetKind: api + targetType: http + values: + - url + - baseUrl + - hostname + - port + - scheme + - username + - password + - token + - tls + - field: configuration.alternatives[].env[].property + targetKind: api + targetType: http + values: + - url + - baseUrl + - hostname + - port + - scheme + - username + - password + - token + - tls + - field: configuration.env[].property + targetKind: datastore + targetType: relational + values: + - url + - hostname + - port + - scheme + - username + - password + - database + - tls + - field: configuration.alternatives[].env[].property + targetKind: datastore + targetType: relational + values: + - url + - hostname + - port + - scheme + - username + - password + - database + - tls + - field: configuration.env[].property + targetKind: datastore + targetType: document + values: + - url + - hostname + - port + - scheme + - username + - password + - database + - tls + - field: configuration.alternatives[].env[].property + targetKind: datastore + targetType: document + values: + - url + - hostname + - port + - scheme + - username + - password + - database + - tls + - field: configuration.env[].property + targetKind: cache + targetType: key_value + values: + - url + - hostname + - port + - scheme + - username + - password + - database + - token + - tls + - field: configuration.alternatives[].env[].property + targetKind: cache + targetType: key_value + values: + - url + - hostname + - port + - scheme + - username + - password + - database + - token + - tls + + schemas: + - id: configuration-shape + description: Validates the environment configuration field shape. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + configuration: + type: object + oneOf: + - required: + - env + properties: + env: + $ref: '#/$defs/envList' + additionalProperties: false + - required: + - alternatives + properties: + alternatives: + type: array + minItems: 2 + items: + type: object + required: + - env + properties: + env: + $ref: '#/$defs/envList' + additionalProperties: false + additionalProperties: false + additionalProperties: true + $defs: + envList: + type: array + minItems: 1 + uniqueItems: true + items: + $ref: '#/$defs/envInput' + envInput: + type: object + required: + - property + - name + properties: + property: + type: string + minLength: 1 + name: + type: string + pattern: '^[A-Za-z_][A-Za-z0-9_]*$' + sensitive: + type: boolean + required: + type: boolean + additionalProperties: false + + - id: configuration-properties-api-http + appliesToKind: api + appliesToInterfaceType: http + description: Validates allowed environment configuration properties for HTTP API integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + configuration: + $ref: '#/$defs/configuration' + additionalProperties: true + $defs: + allowedProperty: + enum: + - url + - baseUrl + - hostname + - port + - scheme + - username + - password + - token + - tls + configuration: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + alternatives: + type: array + items: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + envInput: + type: object + properties: + property: + $ref: '#/$defs/allowedProperty' + + - id: configuration-properties-datastore-relational + appliesToKind: datastore + appliesToInterfaceType: relational + description: Validates allowed environment configuration properties for relational datastore integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + configuration: + $ref: '#/$defs/configuration' + additionalProperties: true + $defs: + allowedProperty: + enum: + - url + - hostname + - port + - scheme + - username + - password + - database + - tls + configuration: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + alternatives: + type: array + items: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + envInput: + type: object + properties: + property: + $ref: '#/$defs/allowedProperty' + + - id: configuration-properties-datastore-document + appliesToKind: datastore + appliesToInterfaceType: document + description: Validates allowed environment configuration properties for document datastore integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + configuration: + $ref: '#/$defs/configuration' + additionalProperties: true + $defs: + allowedProperty: + enum: + - url + - hostname + - port + - scheme + - username + - password + - database + - tls + configuration: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + alternatives: + type: array + items: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + envInput: + type: object + properties: + property: + $ref: '#/$defs/allowedProperty' + + - id: configuration-properties-cache-key-value + appliesToKind: cache + appliesToInterfaceType: key_value + description: Validates allowed environment configuration properties for key/value cache integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + configuration: + $ref: '#/$defs/configuration' + additionalProperties: true + $defs: + allowedProperty: + enum: + - url + - hostname + - port + - scheme + - username + - password + - database + - token + - tls + configuration: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + alternatives: + type: array + items: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + envInput: + type: object + properties: + property: + $ref: '#/$defs/allowedProperty' diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/third-party-example/aws-object-store-v1alpha1.yaml b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/third-party-example/aws-object-store-v1alpha1.yaml new file mode 100644 index 000000000..471a1bab4 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/extensions/third-party-example/aws-object-store-v1alpha1.yaml @@ -0,0 +1,118 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition + +metadata: + uri: https://aws.example.com/runtimeconditions/object-store + version: v1alpha1 + +spec: + dependencies: + - https://runtimeconditions.io/extensions/common-integrations:v1alpha1 + - https://runtimeconditions.io/extensions/env-configuration:v1alpha1 + + kinds: + - name: aws.object_store + + interfaceTypes: + - name: aws.s3 + targetKind: aws.object_store + + interfaceFields: + - name: bucketClass + targetKind: aws.object_store + targetType: aws.s3 + + fieldValues: + - field: interface.bucketClass + targetKind: aws.object_store + targetType: aws.s3 + values: + - standard + - archive + - field: configuration.env[].property + targetKind: aws.object_store + targetType: aws.s3 + values: + - bucket + - region + - accessKeyId + - secretAccessKey + - sessionToken + - field: configuration.alternatives[].env[].property + targetKind: aws.object_store + targetType: aws.s3 + values: + - bucket + - region + - accessKeyId + - secretAccessKey + - sessionToken + + schemas: + - id: aws-s3-interface + appliesToKind: aws.object_store + appliesToInterfaceType: aws.s3 + description: Validates the aws.s3 interface shape. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: + - kind + - interface + properties: + kind: + const: aws.object_store + interface: + type: object + required: + - type + properties: + type: + const: aws.s3 + bucketClass: + enum: + - standard + - archive + additionalProperties: true + additionalProperties: true + + - id: aws-s3-configuration-properties + appliesToKind: aws.object_store + appliesToInterfaceType: aws.s3 + description: Validates allowed environment configuration properties for AWS S3 integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + configuration: + $ref: '#/$defs/configuration' + additionalProperties: true + $defs: + allowedProperty: + enum: + - bucket + - region + - accessKeyId + - secretAccessKey + - sessionToken + configuration: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + alternatives: + type: array + items: + type: object + properties: + env: + type: array + items: + $ref: '#/$defs/envInput' + envInput: + type: object + properties: + property: + $ref: '#/$defs/allowedProperty' diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/relationship-to-adjacent-work.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/relationship-to-adjacent-work.md new file mode 100644 index 000000000..6d38771ce --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/relationship-to-adjacent-work.md @@ -0,0 +1,14 @@ +# Relationship to adjacent work + +Runtime Conditions Profiles are not intended to replace workload specifications, package formats, service catalogs, or provisioning systems. + +The profile describes what one workload needs at runtime: APIs it calls, datastores it depends on, caches it expects, configuration inputs it consumes, and similar integration requirements. It does not describe how to provision those dependencies, where they run, what credentials are used, etc. + +This makes the profile complementary to existing CNCF and cloud-native work: + +- Score and Radius can use profile data as input to workload or application modeling, while still owning platform-specific resolution. +- Backstage and API catalogs can use API Conditions to validate declared API usage against cataloged contracts. Similarly, Backstage can be used to store Runtime Conditions Profiles once they have been generated. +- Crossplane, Kratix, Dapr, Microcks, and other platform tools can act on validated profile requirements, but their resource models remain separate. +- CNAB and Porter can package or distribute software artifacts that include profiles, as well as use the profile to determine install, upgrade, and uninstall workflows. + +The intended boundary is simple: the Runtime Conditions Profile is a portable requirements document; downstream adapters and platforms turn those requirements into actions. diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/security-and-privacy-considerations.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/security-and-privacy-considerations.md new file mode 100644 index 000000000..b091ca2a2 --- /dev/null +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/review-notes/security-and-privacy-considerations.md @@ -0,0 +1,12 @@ +# Security and privacy considerations + +Runtime Conditions Profiles are designed to describe requirements without embedding fulfillment data. + +Profiles must not contain secret values, credentials, customer data, protected data, or concrete target-environment values. Environment configuration entries name workload-facing inputs such as `POSTGRES_PASSWORD` or `PAYMENTS_API_TOKEN`, but they do not carry the corresponding value. Downstream adapters are responsible for mapping those requested inputs to Secrets, ConfigMaps, or other target-environment artifacts. + +Some things to consider: + +- Profiles can still reveal useful information about a workload's expected behavior. For example, a profile may disclose that a workload calls a payments API, depends on Redis, or needs an object store. +- Generators should avoid emitting values discovered from local developer environments. +- Validators should reject fields that violate the profile shape, unresolved vocabulary, and extension JSON Schema rules. +- Adapters should preserve the profile's distinction between workload requirements and target-environment fulfillment choices. diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/runtime-conditions-profile-specification.md similarity index 100% rename from tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/runtime-conditions-profile-spec-rfc.md rename to tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/2-spec-draft-and-support-artifacts/runtime-conditions-profile-specification.md diff --git a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/README.md b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/README.md index 0bfa52ead..2651e14c6 100644 --- a/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/README.md +++ b/tags/tag-developer-experience/initiatives/spec-for-declaring-app-integration/README.md @@ -4,6 +4,11 @@ https://github.com/cncf/toc/issues/1797 Spec that lists integration dependencies needed for an application to run successfully, e.g. DBs, message bus, etc. +## Current artifacts + +- `1-research-summary.md` - research summary for existing application dependency and integration specifications. +- `2-spec-draft-and-support-artifacts/` - Runtime Conditions Profile draft, extension definitions, complete profile examples, and short review notes. + ## Initiative description One of the common things we hear in software development is that if we package an application a certain way, it can run anywhere. While that may be true in terms of executing the command that runs it, it doesn’t guarantee that the application won’t exit 1 within a few milliseconds when it can’t connect to a database or cache, or start throwing 500s when it tries to call to a peer service that hasn’t been deployed. Yes, it can run, but can it run successfully?