Education
LessonIntroductory programming, data engineering, or A-level computing · 55 min

When a Catalog Number Outgrows Its Format

The Two-Line Element format reserves exactly five characters for the catalog number. The catalog passed 99,999. This lesson makes that abstract lesson about fixed-width fields concrete, with an endpoint that really does return an error.

data-formatstleommidentifiersapilegacy-systemserror-handling
Download Word document (.doc)

You may print and copy this lesson for one classroom or one family, for as many years as you teach it. You may not resell it or post the file publicly.

Overview

The Two-Line Element set is one of the most widely implemented data formats in existence. It is also fifty-odd years old, and it is fixed-column: every field lives at a hard-coded character position. CelesTrak’s format documentation gives the catalog number as columns 3 to 7 of line 1. Five characters. Not five characters or more.

That was fine while the catalog held fewer than 100,000 objects. It stopped being fine on 11 July 2026, when an object named SARAMAGO was catalogued as number 100000. CelesTrak records the event plainly: they ran out of five-digit catalog numbers with the addition of Saramago on 2026-07-11, all newly catalogued objects now have six-digit numbers of 100000 and above, and GP data will not be available for them using the TLE format.

This is not a hypothetical exercise about legacy systems. It is a live one, and you can watch it fail in a single HTTP request. OrbitalWiki serves both formats and marks each record with `has_tle` and `has_omm` flags, so the boundary is visible in the data before you hit it.

The replacement already exists and has for years. The CCSDS Orbit Mean-Elements Message, distributed as XML, JSON, KVN, or CSV, treats the catalog number as an actual number rather than a five-character slot. CelesTrak introduced those formats in 2020 precisely so this migration would be possible, and argues that since every developer will have to update their code anyway, it is worth doing in a way that does not rely on fixed-width fields again.

There is a stopgap you will meet in other people’s code, called Alpha-5, which replaces the leading digit with a letter to stretch the same five characters further. It buys headroom and nothing more. It is worth recognising when you see it, and worth not building on.

At a glance

Learning objectives

  • Explain what a fixed-width record format is and what happens when a value exceeds its field.
  • Locate the catalog-number field in a TLE and state its width from the format documentation.
  • Reproduce a real format failure against a live API and read the error response correctly.
  • Retrieve the same object in a format that has room, and explain what changed.
  • Write code or pseudocode that degrades to the newer format rather than crashing or silently dropping records.

Prerequisites

  • Basic HTTP requests, with curl, a browser, or any client library.
  • Familiarity with JSON.

Required software

  • A browser, curl, or an HTTP client. An OrbitalWiki API key if authenticated requests are required.

Dataset version

OrbitalWiki live catalog. Record the dataset-release label from /datasets when available, or the exact access date for a live lookup.

Student materials

Format-boundary worksheet (request log and fallback design)CSV, opens in any spreadsheet app
Download

Student instructions

  1. 1Read the CelesTrak TLE format documentation and write down the exact column range of the catalog-number field on line 1. State the field width in characters.
  2. 2Request the TLE for a five-digit object, for example NORAD 25544, from /api/v1/satellites/25544/tle. Record the status code and confirm the catalog number appears where the documentation says it should.
  3. 3Now request /api/v1/satellites/100000/tle. Record the status code and the full error body verbatim. Do not treat it as a bug.
  4. 4Read the hint in that error body and follow it: request /api/v1/satellites/100000/omm. Record the status code, and the catalog number and object ID as returned.
  5. 5Explain in two sentences what is different about the second format, and why the first one cannot be patched to hold this value.
  6. 6Query the list endpoint and find records where has_tle is false but has_omm is true. Record your query, the access date, and how many such records you found. Do not copy a count from this lesson: the number grows every week.
  7. 7Write a function or pseudocode that fetches orbital data for any catalog number: try the TLE endpoint, and on a 422 fall back to OMM. It must never drop the record silently and never present a partial result as complete.
  8. 8Write one paragraph on what your code would have done, before this change, if it had assumed catalog numbers were always five characters. Name the specific failure: a crash, a truncated value, a silently skipped record, or a wrong join.

Expected output

  • The field width stated as five characters, columns 3 to 7, cited to the format documentation.
  • A recorded successful TLE response for a five-digit object.
  • A recorded 422 response for the six-digit object, quoted verbatim, treated as correct behaviour.
  • A recorded successful OMM response for the same object.
  • A query log with filter, count, and access date for the has_tle false records.
  • Working fallback code or pseudocode with an explicit error path and no silent drop.
  • A named failure mode for the five-character assumption.
[teacher]

Teacher materials, not student-facing

Teacher answer keyCSV, including why the 422 is correct behaviour
Download

Teaching notes

  • The single most important framing: the 422 is not a broken endpoint. It is a correctly implemented refusal to encode a value the format cannot hold. A student who reports it as a bug has learned the opposite of the intended lesson. Ask them what the alternative would have been: truncating to 10000, or silently emitting a wrong number, both far worse.
  • Step 6 deliberately has no expected number. The count of six-digit objects grows continuously as new objects are catalogued, so the reproducible artefact is the query plus the date, not the answer. This is the same discipline the research-methods lessons teach.
  • Silent truncation is the failure mode worth dwelling on. A crash is loud and gets fixed. A parser that reads columns 3 to 7 of a six-digit number and returns a plausible-looking wrong catalog number produces corrupted joins that can go unnoticed for months.
  • If students meet Alpha-5 in third-party code or documentation, explain it as a stopgap that widens the same five characters using letters, and note that CelesTrak chose not to use it for new objects. Recognising it matters; adopting it does not.
  • This lesson pairs naturally with the record-matching lesson: a truncated catalog number is exactly the kind of corruption that makes a cross-catalog join produce confident nonsense.
  • For a stronger group: ask why the designers of the TLE chose fixed columns at all. Punched cards, teletype links, and parsers written without string libraries all made it a reasonable decision in its era. The lesson is not that they were foolish, it is that formats outlive their assumptions.

Answer key

Where does the catalog number live in a TLE, and how wide is the field?
Columns 3 to 7 of line 1 (and of line 2). Five characters, fixed.
What status does /api/v1/satellites/100000/tle return?
A 422, with an error stating that the TLE format cannot encode this six-digit NORAD catalog ID and a hint pointing to the OMM endpoint for the same object.
Is that 422 a bug?
No. It is the correct response. The format genuinely cannot represent the value, and refusing is better than truncating or emitting a wrong number.
What is different about the OMM format?
It is a structured message (JSON, XML, KVN, or CSV) in which the catalog number is a numeric value rather than a fixed-width character field, so it has no five-character ceiling.
When did five-digit catalog numbers run out?
11 July 2026, with the cataloguing of SARAMAGO as object 100000. CelesTrak states that all newly catalogued objects now receive six-digit numbers of 100000 and above.
Why can the TLE not simply be widened?
Every other field on the line is positioned by absolute column. Adding a character to one field shifts all of them, so every existing parser in the world would break. That is what fixed-width means.
What is the worst failure mode for a parser that assumes five characters?
Silent truncation. It produces a valid-looking but wrong catalog number, which then joins to the wrong object. A crash would be far easier to detect.
What must the fallback code never do?
Drop a record without signalling it, or present a partial result as though it were complete.

How to cite

Cite the CelesTrak format pages for the field definitions and the catalog-number transition, and cite each API request by endpoint path, status code, and UTC access time. Never include credentials in a citation.

Need this lesson in another language?

Educators can request a translation or a language not yet available for this lesson.

Request this lesson language →

Sources

← All education paths