Versioning Policy

The NIL Taxonomy uses semantic versioning to ensure stability and predictable upgrades.

Version Types

Taxonomy Version (Data)

The taxonomy version represents the schema and data definitions.

Format: vMAJOR.MINOR.PATCH (e.g., v1.0.0)

API Version

The API version is in the URL path: /v1/, /v2/, etc.

API versions change only when:

• Endpoint paths change
• Request/response formats change
• Authentication mechanism changes

SDK Version

The SDK follows standard npm semver: MAJOR.MINOR.PATCH

SDK versions track with API versions where possible.

Current Versions

Compatibility Matrix

Taxonomy v1.0  ←→  API v1  ←→  SDK 1.x
Taxonomy v1.1  ←→  API v1  ←→  SDK 1.x
Taxonomy v2.0  ←→  API v2  ←→  SDK 2.x

Checking Versions

In API Responses

All API responses include version headers:

GET /api/nil/v1/licenses
Authorization: Bearer YOUR_KEY
 
HTTP/1.1 200 OK
X-Taxonomy-Version: v1.0
X-API-Version: v1
Content-Type: application/json

In SDK

import { SDK_VERSION } from '@nil-taxonomy/sdk';
 
console.log('SDK Version:', SDK_VERSION); // "1.0.0"

Schema Endpoint

const client = new NILTaxonomyClient({ ... });
const schema = await client.getSchema('v1');
 
console.log('Taxonomy Version:', schema.version); // "v1.0"
console.log('Published:', schema.published_at);

Upgrade Guidelines

Minor Version Upgrades (v1.0 → v1.1)

Safe to adopt immediately. Minor versions are backward compatible.

What changes:

• New dimensions (optional fields)
• New enum values
• New base license templates

What doesn't change:

• Existing dimensions remain the same
• Existing enum values stay valid
• Required fields stay required

Action items:

1. Update SDK to latest version
2. Run tests in staging
3. Deploy to production

npm update @nil-taxonomy/sdk

Major Version Upgrades (v1.x → v2.0)

Requires migration. Major versions may have breaking changes.

What may change:

• Dimensions removed or renamed
• Enum values removed or changed
• Different required fields
• New validation rules

Action items:

1. Review changelog for breaking changes
2. Update SDK: npm install @nil-taxonomy/sdk@2.0.0
3. Update API URL from /v1/ to /v2/
4. Test thoroughly in staging
5. Update validation logic
6. Migrate stored license data
7. Update version display
8. Deploy to production

Deprecation Policy

When a feature is deprecated:

1. Announcement - Marked as deprecated in changelog and docs
2. Warning Header - API returns X-Deprecation-Warning header
3. Grace Period - Minimum 2 minor versions OR 6 months (whichever is longer)
4. Removal - Feature removed in next major version

Example Deprecation

v1.1 - Feature deprecated:

HTTP/1.1 200 OK
X-Deprecation-Warning: exclusive_categories.QSR_FAST_FOOD deprecated in v1.1, use QSR. Removed in v2.0.

v1.2, v1.3 - Still works, still warns

v2.0 - Feature removed:

HTTP/1.1 400 Bad Request
{
  "error": "Invalid enum value: QSR_FAST_FOOD not supported in v2.0. Use QSR."
}

Version Display Requirements

Per the NIL Taxonomy Use License, licensees must display the taxonomy version:

Required contexts:

• User-facing documentation
• API responses (as metadata field)
• Compliance/audit materials

Acceptable formats:

• "Powered by NIL Taxonomy v1.0"
• "Uses NIL Taxonomy v1.0"
• "NIL Taxonomy v1.0"

In code:

{
  license: { ... },
  _meta: {
    taxonomy_version: "v1.0",
    generated_at: "2024-01-15T10:30:00Z"
  }
}

Changelog

Full changelog available at: https://nil-taxonomy.org/changelog (opens in a new tab)

Format

## [v1.1.0] - 2024-12-15
 
### Added
- New dimension: `platform_rights` for platform-specific licensing
- New base license: `NIL-SOCIAL` for social media campaigns
 
### Changed
- Updated `exclusive_categories` descriptions for clarity
- Improved validation error messages
 
### Deprecated
- `QSR_FAST_FOOD` in favor of `QSR` (removed in v2.0)
 
### Fixed
- Typo in `ai_synthetic_use.avatar_only` description

Support Policy

Active: Receives all updates, bug fixes, and support
EOL (End of Life): No longer supported, no updates

Version Notifications

Stay informed about new versions:

Email Notifications

Subscribe at: https://nil-taxonomy.org/updates (opens in a new tab)

API Header

Check for newer versions in API responses:

X-Latest-Version: v1.1
X-Your-Version: v1.0
X-Upgrade-Available: true

RSS Feed

Subscribe to: https://nil-taxonomy.org/changelog.rss (opens in a new tab)

Pinning vs Latest

Pinning (Recommended)

Pin to specific taxonomy version for stability:

// ✅ Pinned version
const dimensions = await client.getDimensions('v1.0');

Benefits:

• Predictable behavior
• No surprise breakages
• Controlled upgrade cycle

Latest

Use latest version for always-current data:

// ⚠️ Latest version
const dimensions = await client.getDimensions('latest');

Risks:

• May receive breaking changes
• Validation may fail unexpectedly
• Requires robust error handling

Migration Best Practices

Test Before Upgrading

// In staging environment
const oldClient = new NILTaxonomyClient({ ..., version: 'v1.0' });
const newClient = new NILTaxonomyClient({ ..., version: 'v1.1' });
 
const oldDimensions = await oldClient.getDimensions();
const newDimensions = await newClient.getDimensions();
 
// Compare and identify changes
const changes = compareVersions(oldDimensions, newDimensions);
console.log('Changes:', changes);

Gradual Rollout

1. Deploy new version to 10% of users
2. Monitor error rates and validation failures
3. Gradually increase to 50%, then 100%
4. Roll back if issues detected

Maintain Backward Compatibility

// Support multiple versions during transition
function validateLicense(license: any, version: string = 'v1.0') {
  if (version === 'v1.0') {
    return validateV1(license);
  } else if (version === 'v1.1') {
    return validateV1_1(license);
  }
  throw new Error(`Unsupported version: ${version}`);
}

Questions?

Contact: support@nil-taxonomy.org