API Versioning
Configure structured version tracking for REST, GraphQL, gRPC, AsyncAPI, Webhook, and MCP API definitions with format-specific controls and automatic version suggestions.
NeoArc Studio supports structured version tracking for all API and schema definitions. Rather than a free-text version field, you choose a version format that determines how versions are validated, compared, and displayed. This applies consistently across REST, GraphQL, gRPC, AsyncAPI, Webhook, and MCP API types, as well as shared schemas.
Version Formats
Select a version format from the dropdown on any API or schema home form. The version input control adapts to show format-appropriate fields.
| Format | Pattern | Input Control | When to Use |
|---|---|---|---|
| Semantic | major.minor.patch | Three numeric inputs (e.g. 2.1.0) | Schemas and detailed API contracts where you need to distinguish breaking, additive, and patch-level changes |
| Major.Minor | major.minor | Two numeric inputs (e.g. 2.1) | APIs where you track breaking and additive changes but do not need patch-level granularity |
| Simple Major | vN | One numeric input with 'v' prefix (e.g. v2) | REST and GraphQL APIs that increment on breaking changes only |
| Date-based | YYYY-MM-DD | Date picker | Continuously evolving APIs where versions follow a release schedule (similar to AWS-style versioning) |
| Custom | Free text | Text input | Legacy or non-standard versioning schemes that do not fit the other formats |
| None | No version | Hidden | When version tracking is not needed (the default) |
Setting a Version Format
Versioning Model
The version format field tells the system how to parse, compare, and suggest version numbers. It does not change the fundamental versioning model in NeoArc, which is based on directory-level forking.
Version Comparison and Suggestions
The version utility system provides automatic version comparison and next-version suggestions based on detected change categories. When a breaking change is detected, the system can suggest a major version bump. Additive changes suggest a minor bump (for semantic and major.minor formats). Patch-level bumps apply only to the semantic format for cosmetic changes.
| Change Type | Semantic | Major.Minor | Simple Major | Date-based |
|---|---|---|---|---|
| Breaking | Major bump (2.0.0) | Major bump (2.0) | Major bump (v3) | No suggestion |
| Additive | Minor bump (1.2.0) | Minor bump (1.2) | No suggestion | No suggestion |
| Deprecation | Minor bump (1.2.0) | Minor bump (1.2) | No suggestion | No suggestion |
| Cosmetic | Patch bump (1.1.1) | No suggestion | No suggestion | No suggestion |