NATO Classification Conversion API

A GraphQL API middleware for converting security classifications between NATO nations using the NATO standard as a "Rosetta Stone".

Quick Links

• GraphQL Endpoint - Production API endpoint
• GraphQL Playground - Interactive API explorer with schema documentation
• Analytics Dashboard - Real-time KPIs and performance metrics
• Nation Analytics - Per-nation request analytics and metadata insights

Table of Contents

1. System Overview
2. Authentication
3. Queries
4. Mutations
5. Metadata Field Reference (DoD Compliant)
6. Complete Examples

1. System Overview

This API provides security classification conversion services for NATO member nations. It uses a two-step conversion process:

Source Nation Classification → NATO Standard → Target Nation Classification(s)

Key Concepts

ConversionRequest

A request to convert a classified document from one nation's terminology to another's

ConversionResponse

The result containing NATO equivalent and target nation classifications

ClassificationSchema

Mapping between a nation's classification levels and NATO standards

Authority

A validated organization authorized to request conversions

2. Authentication

Step 1: Sign In

Obtain a JWT token by signing in with your credentials:

mutation SignIn {
  signIn(input: {
    email: "user@nato.int"
    password: "your_password"
  }) {
    bearer
    email
    role
  }
}

Step 2: Add Token to Headers

Include the bearer token in all subsequent requests:

{
  "Authorization": "Bearer YOUR_JWT_TOKEN_HERE"
}

3. Queries

3.1 Query Conversion Requests

Get All Conversion Requests

query {
  conversionRequests {
    id
    sourceNationCode
    sourceNationClassification
    targetNationCodes
    createdAt
    completedAt
    creator {
      name
      email
    }
  }
}

Get Request by ID

query {
  conversionRequestById(id: "uuid-here") {
    id
    sourceNationCode
    sourceNationClassification
    targetNationCodes
    dataObject {
      title
      description
    }
    metadata {
      domain
      tags
    }
  }
}

Get Pending Requests

query {
  conversionRequestsPending {
    id
    sourceNationCode
    createdAt
  }
}

3.2 Query Conversion Responses

Get All Responses

query {
  conversionResponses {
    id
    natoEquivalent
    targetNationClassifications
    createdAt
    expiresAt
  }
}

Get Response by Request ID

query {
  conversionResponsesByRequestId(requestId: "uuid-here") {
    id
    natoEquivalent
    targetNationClassifications
    subjectData {
      title
    }
  }
}

Get Active (Non-Expired) Responses

query {
  conversionResponsesActive {
    id
    natoEquivalent
    expiresAt
  }
}

3.3 Query Classification Schemas

Get Schema by Nation Code

query {
  classificationSchemasByNationCode(nationCode: "USA") {
    id
    nationCode
    toNatoUnclassified
    toNatoRestricted
    toNatoConfidential
    toNatoSecret
    toNatoTopSecret
    version
  }
}

3.4 Query Nations

query {
  nations {
    id
    nationCode
    nationName
  }
}

3.5 Query Authorities

query {
  authorities {
    id
    name
    email
    nation {
      nationCode
      nationName
    }
  }
}

4. Mutations

4.1 Submit Conversion Request (Main Operation)

Submit a document for classification conversion. This automatically processes the conversion.

mutation SubmitConversion {
  submitConversionRequest(conversionData: {
    userId: "your-user-uuid"
    authorityId: "your-authority-uuid"
    dataObject: {
      title: "Intelligence Report #2024-001"
      description: "Strategic intelligence assessment"
    }
    metadata: {
      identifier: "urn:uuid:550e8400-e29b-41d4-a716-446655440000"
      authorizationReference: "OPORD 24-001"
      authorizationReferenceDate: "2024-01-15T00:00:00"
      originatorOrganizationId: "originator-authority-uuid"
      custodianOrganizationId: "custodian-authority-uuid"
      format: "application/pdf"
      formatSize: 2048576
      securityClassification: "SECRET"
      releasableToCountries: ["USA", "GBR", "FRA"]
      releasableToOrganizations: ["NATO"]
      disclosureCategory: "Category C"
      handlingRestrictions: ["CUI"]
      handlingAuthority: "32 CFR Part 2002"
      domain: "INTEL"
      tags: ["urgent", "classified", "strategic"]
    }
    sourceNationClassification: "SECRET"
    sourceNationCode: "USA"
    targetNationCodes: ["GBR", "FRA", "DEU"]
  }) {
    request {
      id
      createdAt
    }
    response {
      id
      natoEquivalent
      targetNationClassifications
    }
    success
    message
  }
}

4.2 Create Request Without Processing

Create a conversion request for later/batch processing:

mutation CreateRequest {
  createConversionRequest(conversionData: {
    userId: "your-user-uuid"
    authorityId: "your-authority-uuid"
    dataObject: {
      title: "Operational Brief"
      description: "Mission planning document"
    }
    metadata: {
      identifier: "urn:uuid:660e8400-e29b-41d4-a716-446655440001"
      originatorOrganizationId: "originator-authority-uuid"
      custodianOrganizationId: "custodian-authority-uuid"
      format: "application/msword"
      securityClassification: "CONFIDENTIAL"
      releasableToCountries: ["GBR", "USA", "CAN"]
      domain: "OPERATIONS"
      tags: ["planning"]
    }
    sourceNationClassification: "CONFIDENTIAL"
    sourceNationCode: "GBR"
    targetNationCodes: ["USA", "CAN"]
  }) {
    id
    sourceNationCode
    createdAt
  }
}

4.3 Process Existing Request (Admin Only)

mutation ProcessRequest {
  processConversionRequest(requestId: "uuid-here") {
    id
    natoEquivalent
    targetNationClassifications
  }
}

4.4 Mark Request as Completed (Admin Only)

mutation MarkCompleted {
  markConversionRequestCompleted(requestId: "uuid-here") {
    id
    completedAt
  }
}

4.5 Delete Request (Admin Only)

mutation DeleteRequest {
  deleteConversionRequest(requestId: "uuid-here")
}

4.6 Metadata Field Reference (DoD Compliant)

All conversion requests must include metadata compliant with DoD Metadata Guidance (January 2023). The metadata structure includes 10 required baseline fields organized into Resource Description and Safeguarding categories.

Required Fields

Optional Fields

Metadata Best Practices

• Use structured identifiers - URN format preferred: urn:uuid:{guid}
• Reference valid Authority IDs - Originator and Custodian must be existing Authority records
• Use standard MIME types - For format field: application/pdf, image/jpeg, text/xml, etc.
• Be specific with classifications - Use exact terms from your nation's ClassificationSchema
• Specify releasability - At least one of: countries, organizations, or categories
• Document restrictions clearly - Include handling authority for audit trail
• Maintain timestamps - Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS) in UTC

Minimal Valid Metadata Example

{
  "identifier": "urn:uuid:550e8400-e29b-41d4-a716-446655440000",
  "originatorOrganizationId": "987e6543-e21b-12d3-a456-426614174000",
  "custodianOrganizationId": "987e6543-e21b-12d3-a456-426614174000",
  "format": "text/plain",
  "securityClassification": "UNCLASSIFIED",
  "domain": "GENERAL",
  "tags": ["test"]
}

Complete Metadata Example

{
  "identifier": "urn:uuid:770e8400-e29b-41d4-a716-446655440002",
  "authorizationReference": "FRAGO 2024-027",
  "authorizationReferenceDate": "2024-03-20T10:30:00",
  "originatorOrganizationId": "987e6543-e21b-12d3-a456-426614174000",
  "custodianOrganizationId": "987e6543-e21b-12d3-a456-426614174000",
  "format": "application/pdf",
  "formatSize": 5242880,
  "securityClassification": "SECRET",
  "releasableToCountries": ["USA", "GBR", "FRA"],
  "releasableToOrganizations": ["NATO"],
  "disclosureCategory": "Category B",
  "handlingRestrictions": ["CUI", "NOFORN"],
  "handlingAuthority": "EO 13526",
  "domain": "INTEL",
  "tags": ["regional", "threat-assessment", "strategic"]
}

5. Complete Examples

Example 1: Complete Conversion Workflow

Scenario: US agency converting SECRET document for UK and France

Step 1: Sign In

mutation {
  signIn(input: {
    email: "analyst@dia.gov"
    password: "SecurePassword123"
  }) {
    bearer
    role
  }
}

Step 2: Submit Conversion (with variables)

Query:

mutation SubmitConversion($input: ConversionRequestInput!) {
  submitConversionRequest(conversionData: $input) {
    request {
      id
      sourceNationCode
      targetNationCodes
    }
    response {
      natoEquivalent
      targetNationClassifications
    }
    success
    message
  }
}

Variables:

{
  "input": {
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "authorityId": "987e6543-e21b-12d3-a456-426614174000",
    "dataObject": {
      "title": "Intelligence Assessment: Eastern Europe",
      "description": "Comprehensive intelligence report on regional threats"
    },
    "metadata": {
      "identifier": "urn:uuid:770e8400-e29b-41d4-a716-446655440002",
      "authorizationReference": "FRAGO 2024-027",
      "authorizationReferenceDate": "2024-03-20T10:30:00",
      "originatorOrganizationId": "987e6543-e21b-12d3-a456-426614174000",
      "custodianOrganizationId": "987e6543-e21b-12d3-a456-426614174000",
      "format": "application/pdf",
      "formatSize": 5242880,
      "securityClassification": "SECRET",
      "releasableToCountries": ["USA", "GBR", "FRA"],
      "releasableToOrganizations": ["NATO"],
      "disclosureCategory": "Category B",
      "handlingRestrictions": ["CUI", "NOFORN"],
      "handlingAuthority": "EO 13526",
      "domain": "INTEL",
      "tags": ["regional", "threat-assessment", "strategic"]
    },
    "sourceNationClassification": "SECRET",
    "sourceNationCode": "USA",
    "targetNationCodes": ["GBR", "FRA"]
  }
}

Expected Response:

{
  "data": {
    "submitConversionRequest": {
      "request": {
        "id": "abc123...",
        "sourceNationCode": "USA",
        "targetNationCodes": ["GBR", "FRA"]
      },
      "response": {
        "natoEquivalent": "NATO SECRET",
        "targetNationClassifications": {
          "GBR": "SECRET",
          "FRA": "SECRET DÉFENSE"
        }
      },
      "success": true,
      "message": "Conversion request submitted and processed successfully"
    }
  }
}

Example 2: Query Request History

query RequestHistory {
  conversionRequestsByCreatorId(
    creatorId: "123e4567-e89b-12d3-a456-426614174000"
  ) {
    id
    sourceNationCode
    sourceNationClassification
    targetNationCodes
    createdAt
    isCompleted
    dataObject {
      title
    }
  }
}

Example 3: Check Classification Schema

Before submitting, verify the correct classification terms for your nation:

query {
  classificationSchemasByNationCode(nationCode: "POL") {
    nationCode
    toNatoUnclassified
    toNatoRestricted
    toNatoConfidential
    toNatoSecret
    toNatoTopSecret
  }
}

Response shows Poland's terminology:

{
  "data": {
    "classificationSchemasByNationCode": [{
      "nationCode": "POL",
      "toNatoUnclassified": "Jawne",
      "toNatoRestricted": "Zastrzeżone",
      "toNatoConfidential": "Poufne",
      "toNatoSecret": "Tajne",
      "toNatoTopSecret": "Ściśle Tajne"
    }]
  }
}

Classification Levels Reference

NATO Standard Levels

Example National Equivalents

API Best Practices

• Always authenticate - Include your JWT token in the Authorization header
• Use correct terminology - Check the ClassificationSchema for your nation's specific terms
• Provide complete metadata - Include all required DoD-compliant metadata fields (see Metadata Field Reference)
• Use structured identifiers - Use URN format for metadata identifiers: urn:uuid:{guid}
• Reference valid authorities - Ensure originator and custodian organization IDs exist in the system
• Specify releasability - Always include at least one releasability field (countries, organizations, or categories)
• Check schema expiration - Classification schemas may expire and be updated
• Handle errors gracefully - The API returns descriptive error messages
• Batch operations - Use createConversionRequest for multiple requests, then process in batch

Error Handling

Common errors and solutions:

"User not authenticated"

Solution: Ensure you've included the JWT token in the Authorization header

"Unknown classification 'X' for nation Y"

Solution: Check the classification schema for the correct terminology for that nation

"Classification schema for nation X has expired"

Solution: Contact an administrator to update the classification schema

"No classification schema found for nation X"

Solution: The nation's schema needs to be created by an administrator

Support & Resources

• GraphQL Playground: /playground - Interactive API explorer with complete schema documentation
• GraphQL Endpoint: /graphql - Production API endpoint
• Schema Introspection: Available in the Playground "Docs" panel

NATO Classification Conversion API v0.2.1
For official use by authorized NATO personnel only.