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

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 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 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 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 to document the new feature behavior.
• Update spec.yaml to add the canonical machine-readable definition.
• Edit 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 automatically validates existing models in the repository. You may need to update auxiliary tooling:

• Modify 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 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:

# 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 – Human-readable specification narrative
• core-spec/spec.yaml – Canonical YAML representation
• core-spec/osi-schema.json – JSON schema for validation
• CONTRIBUTING.md – Full contribution guidelines and CLA requirements
• docs/working_groups.md – Active working groups owning spec sections
• examples/ – Sample semantic models illustrating spec usage
• 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, core-spec/spec.yaml, and 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 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 for human-readable documentation, modify spec.yaml for the canonical machine-readable definition, and edit osi-schema.json to add validation rules. For complete features, also add example models under examples/ and update 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}