Version 1.0

CCG Specification

The Code Context Graph standard for machine-readable code intelligence

Namespace: https://codecontextgraph.com/ontology/v1#

1. Overview

The Code Context Graph (CCG) is an open standard for publishing machine-readable code intelligence. It uses JSON-LD to provide a dense, lossless representation of codebase structure, designed specifically for consumption by AI agents and language models.

Design Principles

Layered — Progressive detail from manifest summaries to full AST data
Semantic — RDF-compatible for SPARQL queries and knowledge graph integration
Interoperable — Works with any LLM, any MCP client, any tooling
Diffable — First-class support for tracking changes between versions

Namespace Prefixes

Prefix	Namespace
ccg:	https://codecontextgraph.com/ontology/v1#
narsil:	https://narsilmcp.com/ontology/v1#
xsd:	http://www.w3.org/2001/XMLSchema#
rdf:	http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs:	http://www.w3.org/2000/01/rdf-schema#

2. Document Types

CCG defines four primary document types, each serving a specific purpose in representing code intelligence.

ManifestEntry point document

The root document providing repository metadata, aggregate statistics, and references to detailed layers. This is the starting point for AI agents to understand a codebase at a glance.

ArchitectureStructural overview

Describes module boundaries, public APIs, dependency relationships, and architectural patterns. Enables AI agents to navigate unfamiliar codebases and understand high-level design decisions.

DiffChange tracking

Captures structural changes between two versions: added/removed symbols, renames, and moves. Enables AI agents to understand evolution and migration paths.

ConstraintQuality rules

Defines architectural constraints and quality gates: complexity limits, dependency rules, and layer violations. Enables CI integration and automated enforcement.

3. Property Reference

Complete reference of all properties defined in the CCG ontology.

Repository Metadata

Property	Type	Description
repository	@id	Container for repository information
name	xsd:string	Repository or project name
url	@id	Repository URL (GitHub, GitLab, etc.)
commit	xsd:string	Git commit SHA at time of analysis
analyzedAt	xsd:dateTime	ISO 8601 timestamp of analysis

Language Statistics

Property	Type	Description
languages	@index container	Map of language names to statistics
files	xsd:integer	Number of files for a language
loc	xsd:integer	Lines of code

Symbol Counts

Property	Type	Description
symbols	object	Container for symbol statistics
total	xsd:integer	Total symbol count
functions	xsd:integer	Function count
classes	xsd:integer	Class count
methods	xsd:integer	Method count
structs	xsd:integer	Struct count (Rust, Go, C)
traits	xsd:integer	Trait count (Rust)
interfaces	xsd:integer	Interface count
enums	xsd:integer	Enum count

Security Findings

Property	Type	Description
security	object	Container for security finding counts
critical	xsd:integer	Critical severity findings
high	xsd:integer	High severity findings
medium	xsd:integer	Medium severity findings
low	xsd:integer	Low severity findings
info	xsd:integer	Informational findings

Quality Metrics

Property	Type	Description
quality	object	Container for code quality metrics
avgCyclomaticComplexity	xsd:decimal	Average cyclomatic complexity
maxCyclomaticComplexity	xsd:integer	Maximum cyclomatic complexity
hotspots	@list	List of complexity hotspots

Layer References

Property	Type	Description
layers	object	Container for layer URIs
architecture	@id	URI to architecture layer document
symbolIndex	@id	URI to symbol index layer
fullDetail	@id	URI to full detail layer
sparqlEndpoint	@id	SPARQL endpoint for RDF queries

4. Examples

Manifest Document

manifest.jsonld

{
  "@context": "https://codecontextgraph.com/ontology/v1",
  "@type": "Manifest",
  "repository": {
    "name": "my-project",
    "url": "https://github.com/org/my-project",
    "commit": "a1b2c3d4e5f6",
    "analyzedAt": "2025-01-15T10:30:00Z"
  },
  "languages": {
    "TypeScript": { "files": 45, "loc": 12000 },
    "Rust": { "files": 23, "loc": 8500 }
  },
  "symbols": {
    "total": 342,
    "functions": 156,
    "classes": 24,
    "methods": 89,
    "interfaces": 18
  },
  "security": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 12
  },
  "layers": {
    "architecture": "https://example.com/ccg/architecture.jsonld",
    "symbolIndex": "https://example.com/ccg/symbols.jsonld",
    "fullDetail": "https://example.com/ccg/full.jsonld",
    "sparqlEndpoint": "https://example.com/sparql"
  }
}

Architecture Document

architecture.jsonld

{
  "@context": "https://codecontextgraph.com/ontology/v1",
  "@type": "Architecture",
  "modules": [
    {
      "name": "core",
      "path": "src/core",
      "purpose": "Core business logic and domain models",
      "exports": ["Engine", "Parser", "Analyzer"],
      "dependsOn": ["utils", "config"]
    },
    {
      "name": "api",
      "path": "src/api",
      "purpose": "HTTP API handlers and routing",
      "exports": ["Router", "handlers"],
      "dependsOn": ["core", "auth"]
    }
  ],
  "publicAPI": [
    {
      "symbol": "Engine.analyze",
      "signature": "async analyze(path: string): Promise<Result>",
      "doc": "Analyzes a codebase at the given path"
    }
  ],
  "patterns": {
    "architectural": ["Layered Architecture", "Dependency Injection"],
    "detected": [
      { "pattern": "Repository", "location": "src/data/*" },
      { "pattern": "Factory", "location": "src/core/factories/*" }
    ]
  }
}

Diff Document

diff-v1.0-v1.1.jsonld

{
  "@context": "https://codecontextgraph.com/ontology/v1",
  "@type": "Diff",
  "base": "https://example.com/ccg/v1.0.0.jsonld",
  "target": "https://example.com/ccg/v1.1.0.jsonld",
  "changes": {
    "added": [
      { "symbol": "StreamProcessor", "file": "src/stream.ts", "line": 1 }
    ],
    "removed": [
      { "symbol": "LegacyParser", "file": "src/legacy.ts" }
    ],
    "renamed": [
      { "old": "processData", "new": "processStream" }
    ],
    "moved": [
      { "symbol": "Utils", "from": "src/utils.ts", "to": "src/lib/utils.ts" }
    ]
  }
}

Constraint Document

constraints.jsonld

{
  "@context": "https://codecontextgraph.com/ontology/v1",
  "@type": "Constraint",
  "constraints": [
    {
      "type": "max-complexity",
      "scope": "function",
      "value": 10
    },
    {
      "type": "no-circular-deps",
      "scope": "module"
    },
    {
      "type": "layer-violation",
      "scope": "module",
      "module": "api",
      "dependsOn": ["core"]
    }
  ]
}

5. Generating CCG Files

The recommended way to generate CCG documents is using narsil-mcp, an open-source MCP server providing deep static analysis across 32 languages.

Generate CCG with narsil-mcp

# Install narsil-mcp
brew install postrv/tap/narsil-mcp

# Generate CCG manifest for a repository
narsil ccg generate ./my-project --output manifest.jsonld

# Generate with all layers
narsil ccg generate ./my-project --full --output ./ccg/

# Export to SPARQL endpoint
narsil ccg export ./my-project --sparql http://localhost:3030/dataset

Note: CCG files can be hosted statically (GitHub Pages, S3, Cloudflare) or served dynamically via SPARQL endpoints. The layers property in manifest documents supports both approaches.

6. RDF & SPARQL

CCG documents are valid JSON-LD, which means they can be converted to RDF triples and queried using SPARQL. This enables powerful cross-repository analysis and integration with knowledge graphs.

Example SPARQL Query

PREFIX ccg: <https://codecontextgraph.com/ontology/v1#>

# Find all functions with high complexity
SELECT ?symbol ?complexity ?file
WHERE {
  ?hotspot a ccg:Hotspot ;
           ccg:symbol ?symbol ;
           ccg:cyclomaticComplexity ?complexity ;
           ccg:file ?file .
  FILTER (?complexity > 15)
}
ORDER BY DESC(?complexity)

Supported Triplestores

Apache Jena / Fuseki
Oxigraph
GraphDB
Amazon Neptune

Conversion Tools

jsonld.js (JavaScript)
rdflib (Python)
sophia_rs (Rust)
Apache Jena riot (CLI)

Start Using CCG

Generate your first Code Context Graph with narsil-mcp

Get narsil-mcp View JSON-LD Schema