diff --git a/2.overview_and_terminology.md b/2.overview_and_terminology.md index 7f3ec30..5a666c9 100644 --- a/2.overview_and_terminology.md +++ b/2.overview_and_terminology.md @@ -42,7 +42,7 @@ The following terms are used throughout this specification. ### Workload Definitions A platform that implements OAM supplies a runtime (or runtimes) that can execute -components. Each type of component that can be run by the OAM runtime is represented by a _workloadDefinition_ that describes the following: +components. Each type of workload that a component can run by the OAM runtime is represented by a _workloadDefinition_ that describes the following: - Metadata: Information about the workload kind - Definition reference: A reference to a schema that defines the workload. The schemas are mostly provided by the OAM @@ -79,7 +79,7 @@ A trait defines a piece of add-on functionality that pertains to the operation o A trait is described as: - Metadata: Information about the trait -- Applies-to list: Enumeration of workloads to which this trait applies +- Applies-to list: Enumeration of workloads types to which this trait applies - Definition reference: A reference to a schema that defines the trait ### Application Scopes @@ -104,7 +104,7 @@ An application configuration has the following parts: ## Representing OAM Objects as Schematics -The OAM specification represents OAM objects (workloads, components, trait definitions, application configurations, etc.) as _schematics_. +The OAM specification represents OAM objects (workload definitions, components, trait definitions, application configurations, etc.) as _schematics_. A schematic is a structured document that provides a declaration of an object or an object's desired state. Throughout this specification, schematics are represented in [YAML](https://yaml.org/). However, nothing in this specification precludes the possibility of representing schematics as JSON documents or other similarly structured textual or binary representations. ### The Structure of a Schematic @@ -209,7 +209,7 @@ The following annotation labels are _predefined_ and RECOMMENDED. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| | `description` | `string` | N | | A short description of the component. | -| `version` | `string` | N | | A string defining the [semantic version](https://semver.org/) of the component. | +| `version` | `string` | N | | A user provided string defining the [semantic version](https://semver.org/) of the component, e.g. the release version of this software| If `version` is not supplied, the default version is assumed to be `0.1.0`, per the [SemVer](https://semver.org/) specification. @@ -229,9 +229,7 @@ The metadata section is used in all schematics. It is also compatible with the K ## Group, Version, and Kind -Many of the API objects described in this document use a naming scheme called "Group, Version, Kind." This scheme, popularized by Kubernetes, provides a consistent way of namespacing and versioning API objects, and it is used here for OAM API versioning. - -> Applications, components, containers, and other entities may have their own versioning schemes. This scheme is solely for the API objects like Component, Application Schematic, Workload, and Traits. +Many of the API objects described in this document use a naming scheme called "Group, Version, Kind." This scheme, popularized by Kubernetes, provides a consistent way of namespacing and versioning API objects, and it is used here for OAM API objects versioning. This section describes the scheme. diff --git a/3.workload.md b/3.workload.md index fd058d7..314aced 100644 --- a/3.workload.md +++ b/3.workload.md @@ -18,7 +18,7 @@ Here are the attributes that provide top-level information about the workload de | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y | | The specific version of the OAM specification in use. The core types use `core.oam.dev/v1alpha2` | +| `apiVersion` | `string` | Y | | A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification | | `kind` | `string` | Y || Must be `WorkloadDefinition` | | `metadata` | [`Metadata`](#metadata) | Y | | Information about the workload definition. | | `spec`| [`Spec`](#spec) | Y | | A container for the workload definition. | diff --git a/4.component.md b/4.component.md index 1452682..00e8f45 100644 --- a/4.component.md +++ b/4.component.md @@ -18,7 +18,7 @@ These attributes provide top-level information about the component definition. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y || The specific version of the OAM specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. | +| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. | | `kind` | `string` | Y || Must be `Component`. | | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the component. | | `spec`| [`Spec`](#spec) | Y || A specification for component attributes. | diff --git a/5.application_scopes.md b/5.application_scopes.md index 0a0fcb5..bb3ffac 100644 --- a/5.application_scopes.md +++ b/5.application_scopes.md @@ -48,7 +48,7 @@ These attributes provide top-level information about the scope definition. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y || The specific version of the OAM specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. | +| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. | | `kind` | `string` | Y || Must be `ScopeDefinition`. | | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the scope. | | `spec`| [`Spec`](#spec) | Y || A specification for scope attributes. | diff --git a/6.traits.md b/6.traits.md index cdde42b..cbf37aa 100644 --- a/6.traits.md +++ b/6.traits.md @@ -63,7 +63,7 @@ The top-level attributes of a trait define its metadata, version, kind, and spec | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y || The specific version of the OAM specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. | +| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. | | `kind` | `string` | Y || Must be `TraitDefinition` | | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the trait. | | `spec`| [`Spec`](#spec) | Y || A specification for trait attributes. | diff --git a/7.application_configuration.md b/7.application_configuration.md index a02d0ae..2b46a80 100644 --- a/7.application_configuration.md +++ b/7.application_configuration.md @@ -59,7 +59,7 @@ The top-level attributes of a application configuration define its metadata, ver | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y || The specific version of the specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. | +| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. | | `kind` | `string` | Y || Must be `ApplicationConfiguration` | | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the application configuration. | | `spec`| [`Spec`](#spec) | Y || A specification for application configuration attributes. | diff --git a/README.md b/README.md index 445ba75..5fef995 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,14 @@ # Open Application Model Specification +[![Gitter](https://badges.gitter.im/oam-dev/community.svg)](https://gitter.im/oam-devcommunity?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) +[![License: MIT](https://img.shields.io/badge/License-OWF-yellow)](https://github.com/oam-dev/spec/blob/master/LICENSE) +[![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/oam-dev/spec)](https://www.tickgit.com/browse?repo=github.com/oam-dev/spec) +[![Follow on Twitter](https://img.shields.io/twitter/follow/oam_dev.svg?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=oam_dev) + |![notification](assets/bell-outline-badge.svg) What is NEW!| |------------------| |May 18th, 2020. [Crossplane](https://github.com/crossplane/crossplane) becomes the standard Kubernetes implementation of OAM spec!| -|Mar 27th, 2020. OAM v1.0.0-alpha.2 is **RELEASED**! The new spec is highly extensible and native to Kubernetes runtime. Check the spec and [What's new in OAM v1alpha2](https://speakerdeck.com/resouer/whats-new-in-oam-v1alpha2-spec) for more detail!| +|Mar 27th, 2020. OAM v0.2.0 is **RELEASED**! The new spec is highly extensible and native to Kubernetes runtime. Check the spec and [What's new in OAM v0.2.0](https://speakerdeck.com/resouer/whats-new-in-oam-v1alpha2-spec) for more detail!| |Mar 26th, 2020. A proof-of-concept project named AWS ECS for OAM is published! Check [the AWS Labs repo ](https://github.com/awslabs/amazon-ecs-for-open-application-model) and have fun with developer centric experience with OAM + Fargate!| Open Application Model is a platform-agnostic specification for building cloud native applications. @@ -63,15 +68,19 @@ The specification convention adopts [Kubernetes Resource Model](https://github.c - [Practical Considerations](8.practical_considerations.md) - [Design Principles](9.design_principles.md) +## Versioning -## Community +Releases of the specification are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [OAM release page](https://github.com/oam-dev/spec/releases). Implementations of the specification are required to specify which version they implement. -### Versioning +### Changes to the API objects -Since July 2020, changes to the specification are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [its release page](https://github.com/oam-dev/spec/releases). Layout (e.g. repo structure, doc format etc) changes are not versioned. Specific implementations of the specification (e.g. OAM Kubernetes Runtime ) should specify which version they implement. +Changes to the API objects in this specification follows [on compatibility](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#on-compatibility) and [incompatible api changes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#incompatible-api-changes) defined in Kubernetes API convention. It doesn't couple with release version of the specification. Changes to the change process (e.g. governance model, review/approve process etc) itself are not currently versioned but may be independently versioned in the future. + +## Community + ### Milestones To get an overview of the milestones and their description please visit the [Milestones](https://github.com/oam-dev/spec/milestones) page. diff --git a/assets/how-it-works.png b/assets/how-it-works.png index f5d44a8..ba977c8 100644 Binary files a/assets/how-it-works.png and b/assets/how-it-works.png differ