# What Is internal.json in is-a.dev? Purpose and Infrastructure Protection

> Discover the purpose of internal.json in is-a.dev. Learn how this file protects infrastructure by managing internal subdomains and blocking user registration for system-managed names.

- Repository: [is-a.dev/register](https://github.com/is-a-dev/register)
- Tags: internals
- Published: 2026-03-09

---

**The [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) file serves as the canonical registry of subdomains reserved for is-a.dev's internal infrastructure, automatically blocking user registration while configuring DNS ignore rules and API metadata for system-managed names.**

The is-a.dev/register repository powers a popular free subdomain service where developers claim `*.is-a.dev` addresses via GitHub pull requests. At the heart of its infrastructure protection lies [`util/internal.json`](https://github.com/is-a-dev/register/blob/main/util/internal.json), a configuration file that explicitly defines which subdomains remain under exclusive system control to prevent conflicts with critical platform services.

## Reserved Subdomains Listed in internal.json

The [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) file contains a JSON array of infrastructure-critical subdomains that the platform treats as system-managed. These entries include:

- **data**
- **docs**
- **ns1**, **ns2**, **ns3**, **ns4**
- **raw**
- **www**

These names represent essential services—name servers, documentation sites, raw API endpoints, and the main website—that must remain available for platform operations regardless of user activity.

## How internal.json Protects Infrastructure

The repository leverages [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) across three distinct systems to ensure internal subdomains remain protected from user registration, public DNS resolution, and accidental exposure.

### Blocking Contributor Registrations via Validation

The test suite enforces that no contributor can create a domain file matching an internal name. In [`tests/json.test.js`](https://github.com/is-a-dev/register/blob/main/tests/json.test.js), the validation logic imports [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) and validates submitted filenames against the reserved list:

```javascript
// tests/json.test.js
const internalDomains = require("../util/internal.json");

t.false(internalDomains.includes(subdomain),
    `${file}: Subdomain name is registered internally`);

```

Any pull request attempting to register `docs.is-a.dev` or `www.is-a.dev` fails automated checks immediately, preserving these names for exclusive platform use.

### Excluding Subdomains from Public DNS Resolution

The DNS configuration generation process explicitly ignores all record types for internal subdomains. In [`dnsconfig.js`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js), the build script appends `IGNORE` rules for each entry in [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json):

```javascript
// dnsconfig.js
var internal = require("./util/internal.json");

internal.forEach(function(subdomain) {
    ignored.push(IGNORE(subdomain, "*"));
});

```

These `IGNORE` rules instruct the DNS provider to drop queries for these subdomains, ensuring they remain unreachable via standard public DNS resolution and protected from accidental exposure.

### Generating Internal API Entries

While hidden from public DNS, internal subdomains appear in the raw API output with standardized metadata pointing to the internal infrastructure. The [`util/raw-api.js`](https://github.com/is-a-dev/register/blob/main/util/raw-api.js) script processes [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) to generate entries mapping each reserved name to `internal.is-a.dev`:

```javascript
// util/raw-api.js
const internal = require(path.join(__dirname, "internal.json"));

for (const subdomain of internal) {
    const commonData = {
        domain: `${subdomain}.is-a.dev`,
        subdomain,
        owner: { username: "is-a-dev" }
    };
    const records = { CNAME: "internal.is-a.dev" };
    v2.push({ ...commonData, records, internal: true });
}

```

This automation ensures API consumers can identify infrastructure ownership through the `internal: true` flag while maintaining accurate service discovery records.

## Summary

- **[`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json)** at [`util/internal.json`](https://github.com/is-a-dev/register/blob/main/util/internal.json) defines the exclusive list of subdomains reserved for platform infrastructure, including name servers and core services.
- **Registration blocking** occurs through [`tests/json.test.js`](https://github.com/is-a-dev/register/blob/main/tests/json.test.js), which validates all new domain requests against the internal list and rejects conflicts.
- **DNS protection** happens via [`dnsconfig.js`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js), where automated `IGNORE` rules prevent public resolution of internal names.
- **API consistency** is maintained by [`util/raw-api.js`](https://github.com/is-a-dev/register/blob/main/util/raw-api.js), which generates canonical CNAME records pointing internal subdomains to `internal.is-a.dev` with appropriate metadata flags.

## Frequently Asked Questions

### What happens if a contributor tries to register an internal subdomain?

The continuous integration pipeline executes [`tests/json.test.js`](https://github.com/is-a-dev/register/blob/main/tests/json.test.js), which imports [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) and checks every submitted filename against the reserved list. If the requested subdomain matches an internal entry, the test fails with a descriptive error message stating the subdomain is registered internally, automatically blocking the pull request from merging.

### Can internal subdomains resolve through public DNS?

No. According to the source code in [`dnsconfig.js`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js), every subdomain listed in [`internal.json`](https://github.com/is-a-dev/register/blob/main/internal.json) receives an `IGNORE(subdomain, "*")` rule that instructs the DNS provider to discard all queries for those names. This prevents both intentional hijacking and accidental public exposure while the platform routes these addresses through internal mechanisms.

### Why do internal subdomains appear in the API output if they are hidden from DNS?

The [`util/raw-api.js`](https://github.com/is-a-dev/register/blob/main/util/raw-api.js) generator explicitly includes internal entries to maintain accurate ownership records and enable service discovery. Each internal subdomain receives a CNAME record pointing to `internal.is-a.dev` and an `internal: true` boolean flag, allowing API consumers to distinguish system-managed infrastructure from user registrations while understanding their canonical configuration.

### How can a new subdomain be added to the internal list?

Adding entries to [`util/internal.json`](https://github.com/is-a-dev/register/blob/main/util/internal.json) requires repository maintainer privileges since modifications affect core infrastructure across three critical systems. The file uses a standard JSON array format, but any addition must be accompanied by corresponding updates to dependent validation logic in [`tests/json.test.js`](https://github.com/is-a-dev/register/blob/main/tests/json.test.js), DNS configuration in [`dnsconfig.js`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js), and API generation in [`util/raw-api.js`](https://github.com/is-a-dev/register/blob/main/util/raw-api.js) to ensure consistent protection.