Dated source reference. Current release status: handoff state. Full original relative paths are in the developer archive.

College roster authoring standard — version 1

Private editor source 0.1.0.dev8 adds the College Fields form and bulk metadata CSV. The hosted dev7 download is unchanged. The machine-readable contract is college-fields-v1.json; the companion container remains extension format 1. These versions are independent of API/native ABI versions.

The current browser editor exposes these same fields directly in the grid, column presets and bulk tools. Its mixed CSV starts ID,ROS_SHA256,EXTRAS_SHA256,..., protecting both native and metadata revisions; reexport after teammate changes. This web contract supplements the preserved desktop instructions below. The91-field vocabulary and extension format remain unchanged.

All 91 fields are optional. Start with the Recommended view; use All fields or a group when needed. Unknown information should stay Not set or Unknown, rather than being filled with invented values. No new field changes native gameplay, selects a rules profile, loads artwork or renders presentation. The hook/API do not consume this vocabulary yet.

Start here

1. Open the roster and select a team or player record.
2. Open Tools → College fields, or the College fields toolbar button. The form offers field descriptions, examples, enum dropdowns, true/false choices and a color picker. Filtering never discards hidden edits.
3. Not set removes a field. Unknown stores an explicit JSON null. Value stores the value you enter. Opening the form creates no defaults or guessed information.
4. Apply the changes. They share the editor's Undo/Redo and change review.
5. Use Save a copy and keep the .ROS and .ROS.openhoops.json pair together. Do not rename or attach an unmatched companion to another roster. Native game saving can invalidate the pair; no automatic reconciliation is claimed.

Tools → Roster / season fields edits dataset title/version/credits, season context and the default ID namespace. Existing native names, ratings, positions, jersey numbers, team assignments and colors remain in their existing tables. Optional display fields describe future consumer overrides; leave them unset when native values suffice.

Recommended authoring priorities

Player class, availability, seasons played/remaining and transfer background are creator declarations. The editor does not calculate eligibility, enforce participation, set injuries or rewrite lineups from these values. High school and previous college are separate fields. There are no redshirt fields in this vocabulary.

NCAA D1 / D2 / D3 and NAIA

Set these team fields for each school in a mixed roster:

These values have no relationship to the native NBA Division column. A roster-level competition value describes dataset context; it does not silently assign all teams in a mixed dataset. Individual team values are explicit. Leave unknown information unset/null; do not identify NAIA as an NCAA division.

Stable identities and 90+ conferences

Use string IDs, for example team north-university and conference northern-conference, in a creator-owned ID namespace such as com.example.college. IDs are case-sensitive, preserve leading zeros and must remain stable when names or physical rows change. An ID namespace is the creator/dataset identity; an entity ID is not an executable address or a physical row number.

org.openhoops.identity.namespace on a record overrides the roster namespace. An absent record namespace inherits the roster value; an explicit null means unknown and suppresses that fallback. The record's identity.id never inherits. A previous-college ID and conference ID use the containing record's effective namespace. This version does not resolve cross-namespace links or infer identity from a name.

On every team in a conference, set the same conference ID, name and abbreviation. Optional conference subdivision is a label such as East/West; it is distinct from competition division. Schools can have different NCAA levels and separate conference identities without changing native packed fields. A conference's identity is the pair (ID namespace, conference ID). Only declared members are listed; empty conferences need a future separate package/app registry.

For an independent, explicitly set org.openhoops.conference.independent=true and leave conference identity fields unset/null. Missing conference information alone means unknown, not independent. A team with independent=false and no ID is still missing conference information.

Tools → Conference declarations groups teams by those IDs and reports conflicting conference labels, duplicate stable entity IDs and missing namespaces. Check roster includes the metadata warnings. No realignment, scheduling, standings or native playoff behavior is inferred or changed. Metadata grouping has no 90-conference cap within the existing companion/record bounds.

The native field is only four bits. Original instruction inspection and bounded execution show regular division IDs 0–2 map to one native conference category, 3–5 to the other, and 6–9 to other. Unused IDs 10–15 exceed the lookup's valid dispatch entries. Expanding native association/standings/scheduling/playoffs therefore needs broader recovery and changes; changing a byte or renaming a conference is insufficient. See conference research.

Rankings and changing season data

org.openhoops.ranking.national_rank is the preferred positive numeric rank for a future consumer. Add national_source (for example ap or coaches) and national_as_of (YYYY-MM-DD). national_status=ranked requires a rank. unranked and unknown require that numeric rank be absent/null. A positive rank by itself supplies a rank; missing status never automatically means unranked. Zero is not a national rank.

AP and coaches polls also have optional separate rank/status/date fields. NET is a separate metric rank. None automatically replace the preferred national value. No polls or proprietary data are downloaded, calculated or supplied. A tournament seed is a separate postseason value.

The catalog marks changing fields with lifecycle=season_or_match: rankings, season records, postseason context, availability, class/season participation and staff career totals. They are authored baselines. A future client/consumer must explicitly advertise support and its match-override behavior before these fields can be promised as live features. This task does not introduce runtime overrides or a scorebug. A future match value must not silently mutate the source roster.

Bulk metadata CSV

Select Teams, Players or another supported table. Tools → Export college CSV exports either Recommended or All standard fields, across the entire selected table. The CSV contains ID, ROS_SHA256, read-only NativeLabel context and fully qualified field keys. It is not limited to the visible editor page or current filter. Imports address existing physical rows and require the same native roster revision hash; they do not match people or teams by names.

• Blank cell: leave the existing value unchanged.
• @unset: remove the field.
• @unknown: explicit unknown/null.
• Text starting with @: prefix another @, so literal @unknown becomes @@unknown.
• Boolean: true / false. Integer: whole decimal number. Text enums: use the catalog's exact lowercase values.
• Do not modify ID or ROS_SHA256 to transplant metadata between unrelated rosters. Export again after native/row edits. NativeLabel is context only and never writes a native name.

Tools → Import college CSV validates the complete file before applying it as one undoable transaction. Wrong-scope columns, duplicate rows/headers, stale roster hashes, invalid dates/types or contradictory rank values refuse the whole import. Custom fields not mentioned in the CSV remain intact. Files are bounded to 16 MiB and export refuses existing destinations. A partial CSV can contain a subset of rows and standard columns, while retaining ID/hash columns.

CLI equivalents, using the same writer:

python run.py college-fields --section 10
python run.py export-college Source.ROS Teams.csv --section 10
python run.py export-college Source.ROS Players.csv --section 3 --profile all
python run.py import-college Source.ROS Teams.csv Edited.ROS --section 10
python run.py export-college Source.ROS Season.csv --profile all
python run.py conferences Edited.ROS

Custom fields remain available through Extra fields using a namespace controlled by the mod/app, such as com.example.scouting.role. They do not require registration here. The org.openhoops namespace is reserved for published OpenHoops contracts. Unknown/future fields are preserved without assigning them invented semantics. Values remain scalar text/numbers/booleans/null; complex dynasty state belongs in an app document.

Complete version-1 field catalog

The following table is generated from the machine-readable catalog. Every row is optional and accepts explicit null. Examples are fictional authoring examples, not current season data. Scopes: roster, team, player (including native player-template tables), staff, arena, uniform, school (native Colleges table).

Windows verification

Private source53b passes148 Windows writer tests (101 existing writer +15 preparation +32 college), MS .NET compilation with warnings-as-errors,32 college cases against the independently assembled factual-catalog runtime, and16 production-EXE control/edit/save/fresh-open checks. Corrected player/team controls were visually inspected through service-session captures; this is not physical-user desktop certification. The original-instruction conference fixture adds49 bounded cases. No game/API/native DLL build, new dependency, shared desktop input or public package is required. Exact identities and scoped evidence are in the checkpoint.