Skip to content

JSON_SCHEMA.md

Latest commit

 

History

History
348 lines (310 loc) · 8.83 KB

JSON_SCHEMA.md

File metadata and controls

348 lines (310 loc) · 8.83 KB

JSON Schema Documentation

Overview

This document defines the JSON schema for the repository metadata file generated by Phase 1 of the GitHub Organization Repository Indexer.

Root Structure

{
  "metadata": {
    "generated_at": "2025-10-16T14:30:00Z",
    "organization": "example-org",
    "total_repositories": 42,
    "tool_version": "1.0.0",
    "github_api_version": "2022-11-28"
  },
  "repositories": [...]
}

Metadata Object

Field Type Description
generated_at string (ISO 8601) Timestamp when data was collected
organization string GitHub organization name
total_repositories integer Number of repositories included
tool_version string Version of the collection script
github_api_version string GitHub API version used

Repository Object

Each repository in the repositories array contains:

{
  "basic_info": {...},
  "status": {...},
  "activity": {...},
  "languages": {...},
  "license": {...},
  "topics": [...],
  "readme_preview": "...",
  "ownership": {...}
}

Basic Info

"basic_info": {
  "name": "awesome-project",
  "full_name": "example-org/awesome-project",
  "description": "An awesome project that does amazing things",
  "url": "https://github.com/example-org/awesome-project",
  "html_url": "https://github.com/example-org/awesome-project",
  "homepage": "https://awesome-project.dev",
  "created_at": "2023-01-15T10:30:00Z",
  "updated_at": "2025-10-15T08:45:00Z",
  "pushed_at": "2025-10-14T16:20:00Z",
  "size": 1024,
  "default_branch": "main",
  "visibility": "public"
}
Field Type Description
name string Repository name
full_name string Full name with organization
description string | null Repository description
url string API URL
html_url string Web URL
homepage string | null Project homepage URL
created_at string (ISO 8601) Creation timestamp
updated_at string (ISO 8601) Last update timestamp
pushed_at string (ISO 8601) Last push timestamp
size integer Repository size in KB
default_branch string Default branch name
visibility string "public" or "private"

Status

"status": {
  "is_archived": false,
  "is_fork": false,
  "is_template": false,
  "is_disabled": false,
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "has_discussions": false
}
Field Type Description
is_archived boolean Repository is archived
is_fork boolean Repository is a fork
is_template boolean Repository is a template
is_disabled boolean Repository is disabled
has_issues boolean Issues are enabled
has_projects boolean Projects are enabled
has_wiki boolean Wiki is enabled
has_pages boolean GitHub Pages is enabled
has_downloads boolean Downloads are enabled
has_discussions boolean Discussions are enabled

Activity

"activity": {
  "stars": 245,
  "watchers": 245,
  "forks": 32,
  "open_issues": 8,
  "open_pull_requests": 3,
  "last_commit_date": "2025-10-14T16:20:00Z",
  "commit_count_30d": 15,
  "contributor_count": 8
}
Field Type Description
stars integer Star count
watchers integer Watcher count
forks integer Fork count
open_issues integer Open issues count
open_pull_requests integer Open PR count
last_commit_date string (ISO 8601) Last commit timestamp
commit_count_30d integer Commits in last 30 days
contributor_count integer Total unique contributors

Languages

"languages": {
  "primary": "Python",
  "breakdown": {
    "Python": 75.5,
    "JavaScript": 15.2,
    "HTML": 6.3,
    "CSS": 3.0
  }
}
Field Type Description
primary string | null Primary language
breakdown object Language percentages (language name -> percentage)

License

"license": {
  "key": "mit",
  "name": "MIT License",
  "spdx_id": "MIT",
  "url": "https://api.github.com/licenses/mit"
}
Field Type Description
key string | null License key
name string | null License name
spdx_id string | null SPDX identifier
url string | null License API URL

Note: All fields may be null if no license is detected.

Topics

"topics": ["python", "automation", "github-api", "documentation"]

Array of strings representing repository topics/tags.

README Preview

"readme_preview": "# Awesome Project\n\nThis project does amazing things...\n\n## Features\n- Feature 1\n- Feature 2"

First 500 characters of the README.md file, or null if no README exists.

Ownership

"ownership": {
  "owner": {
    "login": "example-org",
    "type": "Organization",
    "url": "https://github.com/example-org"
  },
  "top_contributors": [
    {
      "login": "alice",
      "contributions": 156,
      "profile_url": "https://github.com/alice"
    },
    {
      "login": "bob",
      "contributions": 89,
      "profile_url": "https://github.com/bob"
    }
  ],
  "teams": [
    {
      "name": "core-team",
      "permission": "admin"
    },
    {
      "name": "contributors",
      "permission": "write"
    }
  ],
  "codeowners": {
    "exists": true,
    "owners": ["@example-org/core-team", "@alice"]
  }
}
Field Type Description
owner object Repository owner information
top_contributors array Top 5 contributors by commit count
teams array Teams with access (if accessible)
codeowners object CODEOWNERS file information

Complete Example

{
  "metadata": {
    "generated_at": "2025-10-16T14:30:00Z",
    "organization": "example-org",
    "total_repositories": 2,
    "tool_version": "1.0.0",
    "github_api_version": "2022-11-28"
  },
  "repositories": [
    {
      "basic_info": {
        "name": "awesome-project",
        "full_name": "example-org/awesome-project",
        "description": "An awesome project that does amazing things",
        "url": "https://api.github.com/repos/example-org/awesome-project",
        "html_url": "https://github.com/example-org/awesome-project",
        "homepage": "https://awesome-project.dev",
        "created_at": "2023-01-15T10:30:00Z",
        "updated_at": "2025-10-15T08:45:00Z",
        "pushed_at": "2025-10-14T16:20:00Z",
        "size": 1024,
        "default_branch": "main",
        "visibility": "public"
      },
      "status": {
        "is_archived": false,
        "is_fork": false,
        "is_template": false,
        "is_disabled": false,
        "has_issues": true,
        "has_projects": true,
        "has_wiki": true,
        "has_pages": false,
        "has_downloads": true,
        "has_discussions": false
      },
      "activity": {
        "stars": 245,
        "watchers": 245,
        "forks": 32,
        "open_issues": 8,
        "open_pull_requests": 3,
        "last_commit_date": "2025-10-14T16:20:00Z",
        "commit_count_30d": 15,
        "contributor_count": 8
      },
      "languages": {
        "primary": "Python",
        "breakdown": {
          "Python": 75.5,
          "JavaScript": 15.2,
          "HTML": 6.3,
          "CSS": 3.0
        }
      },
      "license": {
        "key": "mit",
        "name": "MIT License",
        "spdx_id": "MIT",
        "url": "https://api.github.com/licenses/mit"
      },
      "topics": ["python", "automation", "github-api", "documentation"],
      "readme_preview": "# Awesome Project\n\nThis project automates GitHub workflows...",
      "ownership": {
        "owner": {
          "login": "example-org",
          "type": "Organization",
          "url": "https://github.com/example-org"
        },
        "top_contributors": [
          {
            "login": "alice",
            "contributions": 156,
            "profile_url": "https://github.com/alice"
          },
          {
            "login": "bob",
            "contributions": 89,
            "profile_url": "https://github.com/bob"
          }
        ],
        "teams": [
          {
            "name": "core-team",
            "permission": "admin"
          }
        ],
        "codeowners": {
          "exists": true,
          "owners": ["@example-org/core-team", "@alice"]
        }
      }
    }
  ]
}

Validation

The generated JSON should:

  1. Be valid JSON (parseable)
  2. Contain all required top-level fields
  3. Have at least one repository in the array
  4. Each repository should have all required sections
  5. Dates should be in ISO 8601 format
  6. Numbers should be non-negative integers
  7. URLs should be valid HTTPS URLs