# How to Contribute New Features or Changes to the Apache Ossie Specification

> Contribute to the Apache Ossie specification by proposing changes on the dev mailing list, submitting a pull request, and getting PPMC approval. Learn the merge process.

- Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie)
- Tags: how-to-guide
- Published: 2026-07-26

---

**To contribute new features or changes to the Apache Ossie specification, announce your proposal on the `dev@ossie.apache.org` mailing list for at least 7 days, open a pull request modifying the `core-spec/` files, and secure three binding +1 votes from the PPMC with no unresolved -1 vetoes before merging.**

The Apache Ossie project standardizes semantic data models through a specification defined in the `core-spec/` directory. When you contribute new features or changes to the Ossie specification, you work with human-readable documentation, machine-readable schema definitions, and formal community governance to ensure interoperability across the ecosystem.

## Understand the Core Specification Files

Before proposing changes, examine the three canonical files that define the Ossie standard.

### Human-Readable Documentation (spec.md)

The [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) file contains the narrative description of model concepts and business logic. When you add features, update this Markdown file to explain new semantics, usage patterns, and examples for end users.

### Canonical Machine-Readable Definition (spec.yaml)

The [`core-spec/spec.yaml`](https://github.com/apache/ossie/blob/main/core-spec/spec.yaml) file provides the authoritative YAML representation of the specification. This file serves as the source of truth for code generators and tooling. Changes to the object model require corresponding updates to this YAML structure.

### Validation Schema (osi-schema.json)

The [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json) file defines the JSON Schema used to validate Ossie models. Any new properties or structural changes must include schema definitions here to enforce validation rules across the ecosystem.

## The Apache Ossie Contribution Workflow

The project follows Apache Software Foundation governance standards requiring public discussion and formal voting for specification changes.

### Step 1: Socialize Your Proposal on the Mailing List

All specification changes must first be announced on `dev@ossie.apache.org`. Post your design rationale, use cases, and proposed implementation to gather feedback. The community requires a minimum **7-day discussion period** (or **72 hours** for a formal vote thread) to allow committers and stakeholders to raise concerns or suggest improvements.

### Step 2: Modify the Core Specification Files

Once the community agrees on the direction, fork the repository and create a topic branch. Update the relevant files in `core-spec/`:

- Modify [`spec.md`](https://github.com/apache/ossie/blob/main/spec.md) to document the new feature behavior.
- Update [`spec.yaml`](https://github.com/apache/ossie/blob/main/spec.yaml) to add the canonical machine-readable definition.
- Edit [`osi-schema.json`](https://github.com/apache/ossie/blob/main/osi-schema.json) to include validation rules for the change.
- Add example models under `examples/` if applicable.

Your pull request must contain a clear title, motivation description, and diffs showing all modified specification files.

### Step 3: Initiate a Formal Vote

Specification changes require a **[VOTE]** thread on the developer mailing list. According to the Apache Ossie governance process:

- At least **three binding +1 votes** from the Podling Project Management Committee (PPMC) are required.
- No **-1 votes** (vetoes) may remain unresolved.
- The vote typically runs for 72 hours minimum.

If the vote passes, a committer merges your pull request and bumps the specification version.

### Step 4: Post-Merge Synchronization

After merging, the updated [`osi-schema.json`](https://github.com/apache/ossie/blob/main/osi-schema.json) automatically validates existing models in the repository. You may need to update auxiliary tooling:

- Modify [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) if validation logic requires enhancement.
- Update converters under `converters/` (e.g., dbt, GoodData) to support the new feature.
- Reference [`docs/working_groups.md`](https://github.com/apache/ossie/blob/main/docs/working_groups.md) to notify relevant working groups of the change.

## Practical Example: Adding a Metadata Field

The following workflow demonstrates adding a new `metadata` property to the Ossie specification:

```bash

# 1. Fork the repo and clone your fork

git clone https://github.com/<your-username>/ossie.git
cd ossie

# 2. Create a feature branch

git checkout -b add-metadata-field

# 3. Edit core-spec/spec.yaml to add the field definition

#    metadata:

#      type: object

#      description: Optional free-form metadata about the semantic model.

# 4. Update core-spec/osi-schema.json to include the property schema

#    Add the metadata property definition to the root object

# 5. Document in core-spec/spec.md

#    ## Metadata

#    A new optional `metadata` object allows contributors to attach arbitrary

#    key/value pairs to a model for downstream tooling.

# 6. Commit and push

git add core-spec/spec.yaml core-spec/osi-schema.json core-spec/spec.md
git commit -m "Add optional metadata field to the OSSIE specification"
git push origin add-metadata-field

# 7. Open a PR and request a [VOTE] on dev@ossie.apache.org

```

## Key Files and Resources

Maintain awareness of these critical paths when contributing:

- **[`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md)** – Human-readable specification narrative
- **[`core-spec/spec.yaml`](https://github.com/apache/ossie/blob/main/core-spec/spec.yaml)** – Canonical YAML representation
- **[`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json)** – JSON schema for validation
- **[`CONTRIBUTING.md`](https://github.com/apache/ossie/blob/main/CONTRIBUTING.md)** – Full contribution guidelines and CLA requirements
- **[`docs/working_groups.md`](https://github.com/apache/ossie/blob/main/docs/working_groups.md)** – Active working groups owning spec sections
- **`examples/`** – Sample semantic models illustrating spec usage
- **[`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py)** – CLI validation tool requiring updates for schema changes
- **`converters/`** – Reference converters that must remain synchronized with spec updates

## Summary

- **Announce first**: Post your proposal to `dev@ossie.apache.org` and wait at least 7 days for community feedback before formally voting.
- **Update three files**: Always modify [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md), [`core-spec/spec.yaml`](https://github.com/apache/ossie/blob/main/core-spec/spec.yaml), and [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json) together to maintain consistency.
- **Secure consensus**: Obtain three binding +1 votes from the PPMC with no unresolved -1 vetoes before merging specification changes.
- **Synchronize tooling**: Update [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) and `converters/` after merging to ensure ecosystem compatibility.

## Frequently Asked Questions

### How long must a proposal discussion remain open before voting?

The Apache Ossie community requires a minimum **7-day discussion period** for specification proposals to allow adequate time for feedback. Once you initiate a formal **[VOTE]** thread, the minimum duration is **72 hours** (3 days) to accommodate time zones and work schedules.

### What is required for a specification change to pass?

A specification change requires at least **three binding +1 votes** from members of the Podling Project Management Committee (PPMC). Additionally, no **-1 votes** (vetoes) may remain unresolved. Binding votes are cast by PPMC members, while non-binding votes from other community members provide valuable feedback but do not count toward the quorum.

### Which files must I update when changing the Ossie specification?

You must synchronize changes across three files in the `core-spec/` directory: update [`spec.md`](https://github.com/apache/ossie/blob/main/spec.md) for human-readable documentation, modify [`spec.yaml`](https://github.com/apache/ossie/blob/main/spec.yaml) for the canonical machine-readable definition, and edit [`osi-schema.json`](https://github.com/apache/ossie/blob/main/osi-schema.json) to add validation rules. For complete features, also add example models under `examples/` and update [`CONTRIBUTING.md`](https://github.com/apache/ossie/blob/main/CONTRIBUTING.md) if the workflow itself changes.

### Do I need to update tooling after a specification change is merged?

Yes. After merging specification changes, you should verify that [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) correctly handles the new schema definitions. If your change affects model structures, update the reference converters in `converters/` (such as dbt or GoodData integrations) to ensure downstream tooling remains compatible with the updated specification.