Skip to main content
All internships are stored in .github/scripts/listings.json. This page documents the schema and structure of listing entries.

​
Overview

The listings.json file contains an array of internship objects. Each object represents a single internship posting with all relevant metadata.

​
Schema Example

A complete listing entry looks like: 
{
    "company_name": "Capital One",
    "locations": ["McLean, VA", "Plano, TX"],
    "title": "Product Development Intern",
    "date_posted": 1690430400,
    "terms": ["Summer 2024"],
    "active": true,
    "url": "https://example.com/job/123",
    "is_visible": true,
    "source": "Simplify",
    "company_url": "",
    "date_updated": 1690430400,
    "sponsorship": null,
    "id": "98b2d671-3f03-430e-b18c-e5ddb8ce5035"
}

​
Field Reference

​
company_name
string
required
Name of the hiring company.Examples:
  • "Google"
  • "Capital One"
  • "Jane Street"
​
company_url
string
Link to the company’s Simplify page. This field is empty for community contributions.Examples:
  • "https://simplify.jobs/c/Google"
  • "" (empty for community contributions)
​
title
string
required
Name of the internship position.Examples:
  • "Software Engineering Internship"
  • "Product Management Intern - MBA"
  • "Machine Learning Research Intern"
​
date_posted
integer
required
Unix timestamp (in seconds) when the internship was added to the list.Example:
  • 1690430400 (July 27, 2023)
​
date_updated
integer
required
Unix timestamp (in seconds) when the listing was last updated.Example:
  • 1690430400
​
url
string
required
Direct link to the job posting/application page.Examples:
  • "https://www.google.com/about/careers/applications/jobs/results/123"
  • "https://capitalone.wd1.myworkdayjobs.com/Capital_One/job/123"
​
terms
array<string>
required
Array of terms/seasons when the internship is available.Examples:
  • ["Summer 2024"]
  • ["Summer 2024", "Fall 2024"]
​
locations
array<string>
required
Array of office locations where the internship is offered.Examples:
  • ["San Francisco, CA"]
  • ["McLean, VA", "Plano, TX", "New York, NY"]
  • ["Remote"]
  • ["Toronto, ON, Canada"]
​
active
boolean
required
Whether the application is currently open.
  • true: Application is open and accepting submissions
  • false: Application is closed or position is filled
​
is_visible
boolean
required
Whether the listing should appear in the README.
  • true: Visible in README tables
  • false: Hidden from README (e.g., removed or spam)
​
source
string
required
Origin of the listing.Examples:
  • "Simplify" - Added by Simplify’s automated system
  • "octocat" - Added by GitHub user @octocat
  • "jane-doe" - Added by GitHub user @jane-doe
​
id
string
required
Unique identifier for the listing (UUID format).Example:
  • "98b2d671-3f03-430e-b18c-e5ddb8ce5035"
​
sponsorship
string | null
Sponsorship status of the position.Values:
  • null or not present - Sponsorship status unknown or not specified
  • "No sponsorship" - Position does not offer visa sponsorship
  • "US Citizenship Required" - Position requires U.S. citizenship
This field controls the display of 🛂 and 🇺🇸 icons in the README.

​
Additional Metadata

While not stored directly in listings.json, the following metadata is derived during README generation:

​
Category

Determined by analyzing the job title and description:
  • Software Engineering
  • Product Management
  • Data Science, AI & Machine Learning
  • Quantitative Finance
  • Hardware Engineering
  • Other

​
Degree Requirements

Indicated by 🎓 icon when the role:
  • Requires Master’s, MBA, or PhD
  • Prefers advanced degrees
  • Is explicitly marked for graduate students

​
Company Tags

  • 🔥 FAANG+ companies (Google, Meta, Apple, Amazon, Microsoft, etc.)
  • 🛂 No sponsorship offered
  • 🇺🇸 U.S. citizenship required

​
Data Validation

The CLI tool includes validation commands to ensure data integrity: 
# Validate schema and data
uv run python main.py listings validate

# Validate and auto-fix issues
uv run python main.py listings validate --fix

​
Common Validation Checks

  • All required fields are present
  • Field types match schema (string, integer, boolean, array)
  • URLs are properly formatted
  • Timestamps are valid Unix timestamps
  • IDs are unique across all listings
  • URLs are unique (no duplicate postings)
  • Categories are valid
  • active and is_visible are boolean values

​
Working with the Schema

​
Reading Listings

import json

with open('.github/scripts/listings.json', 'r') as f:
    listings = json.load(f)

for listing in listings:
    print(f"{listing['company_name']}: {listing['title']}")

​
Adding a Listing

import json
import time
import uuid

new_listing = {
    "company_name": "Example Corp",
    "locations": ["Seattle, WA"],
    "title": "Software Engineering Intern",
    "date_posted": int(time.time()),
    "terms": ["Summer 2026"],
    "active": True,
    "url": "https://example.com/careers/123",
    "is_visible": True,
    "source": "github-username",
    "company_url": "",
    "date_updated": int(time.time()),
    "id": str(uuid.uuid4())
}

with open('.github/scripts/listings.json', 'r') as f:
    listings = json.load(f)

listings.append(new_listing)

with open('.github/scripts/listings.json', 'w') as f:
    json.dump(listings, f, indent=2)
Always use the CLI tool (main.py contribution process) rather than manually editing listings.json to ensure proper validation and formatting.

Build docs developers (and LLMs) love

Get started for freeTalk to us