Schema reference

Every field of every type in the catalog's formats — 38 types, 209 fields. Generated from the JSON Schemas on each build, so this page cannot drift from the files it describes.

For what the vocabulary means — bindings, polarity, coverage, evidence precedence — read the guide instead.

Machine definition

One document per physical machine: what the ROM can address, what each address is on the real playfield, and where every claim came from. This is the file behind each machine page.

schemas/machine.schema.json

machine definition

document root

When schema_version is 2, coverage.dimensions includes spatial_placement.

When coverage.status is author_ready, schema_version is 2.

Field	Type	Req	Notes
format	string		Identifies the document type. Always this exact string. pinmame-machine-definition
schema_version	enum		Version 2 adds optional spatial evidence. Version 1 definitions remain valid, but author-ready definitions must use version 2. 12
machine	machine identity
coverage	coverage
drivers	driver[]		at least 1 item
inputs	input[]
outputs	output[]
displays	display[]
mechanisms	mechanism[]
relationships	relationship[]
sources	source[]
knowledge	knowledge
controller	controller	·
conflicts	conflict[]	·

identifier

value

The shape every id in the catalog takes: lowercase, dot, hyphen or underscore separated.

Used bymachine identity.id,controller.platform,driver.id,driver.clone_of,binding.group,alias.namespace,provenance.source_refs,input.id,input.roles,output.id,output.model,output.roles,display.id,display override.target,mechanism.id,mechanism.actuators,mechanism.sensors,mechanism.positions.id,mechanism.positions.sensors,relationship.id,relationship.source,relationship.destination,source.id,excerpt.id,spatial placement.id,device override.target,conflict.id,conflict.source_refs

Pattern^[a-z0-9]+(?:[._-][a-z0-9]+)*$

machine identity

Used bymachine definition.machine

Field	Type	Req	Notes
id	identifier		The physical product: one playfield, one wiring loom, one definition, however many ROM revisions exist.
name	string		at least 1 character
manufacturer	string		at least 1 character
year	integer		Null where the release year is genuinely unknown rather than merely unrecorded. minimum 1900 · maximum 2100
kind	enum	·	physical_pinballphysical_conversionredemption_gamediagnostic_softwaresystem_softwareunknown
model_number	string	·	at least 1 character
ipdb_id	integer	·	minimum 1
opdb_id	string	·	pattern ^G[A-Za-z0-9]+-[A-Za-z0-9-]+$
playfield	object	·	Optional extent that normalized playfield coordinates map onto, so a consumer can render placements at the correct aspect ratio. Purely presentational: the normalized positions stay authoritative and nothing is required to read this.

machineIdentity.playfield

Optional extent that normalized playfield coordinates map onto, so a consumer can render placements at the correct aspect ratio. Purely presentational: the normalized positions stay authoritative and nothing is required to read this.

Used bymachine identity.playfield

Field	Type	Req	Notes
width	number		Extent along x, the left-to-right axis that normalized x = 0..1 spans. greater than 0
height	number		Extent along y, the rear-to-front axis that normalized y = 0..1 spans. greater than 0
units	enum		vpx records the retained table's own bounds, which are the basis the normalized coordinates were computed from. mm and inch record measured physical dimensions. vpxmminch
provenance	provenance	·

coverage

Used bymachine definition.coverage

Field	Type	Notes
status	enum	Fail-closed. Only the completeness validator may grant author_ready; do not set it by hand. stubpartialauthor_ready
missing	enum[]	The authoring requirements not yet satisfied. Empty is what author_ready requires. identitydriver_mappingcontroller_platforminput_enumerationinput_semanticsoutput_enumerationoutput_semanticsdisplay_inventorymechanism_inventorymechanism_behaviorpolarityvariant_differencesrecreation_notesprovenancespatial_placementunresolved_conflicts unique
dimensions	map of assertion state	How well each axis of the definition is established. Keys are the seven axes below.

Field

Type

Req

Notes

status

enum

Fail-closed. Only the completeness validator may grant author_ready; do not set it by hand.

stubpartialauthor_ready

missing

enum[]

The authoring requirements not yet satisfied. Empty is what author_ready requires.

identitydriver_mappingcontroller_platforminput_enumerationinput_semanticsoutput_enumerationoutput_semanticsdisplay_inventorymechanism_inventorymechanism_behaviorpolarityvariant_differencesrecreation_notesprovenancespatial_placementunresolved_conflicts

unique

dimensions

map of assertion state

How well each axis of the definition is established. Keys are the seven axes below.

assertion state

value

How well one assertion is established. Per claim, not per document — observing that an output toggled is not the same as knowing what it drives, and failing to observe one is not evidence that it is unused.

Used bycoverage.dimensions,provenance.status

Valuesunknowncandidateobservedvalidatedconflictednot_applicable

controller

Used bymachine definition.controller

Field	Type	Req	Notes
platform	identifier		Holds the id of a controller profile.
hardware_generation	string	·	pattern ^0x[0-9a-f]+$
inversion_applied_by_emulator	boolean	·

driver

Used bymachine definition.drivers

Field	Type	Req	Notes
id	identifier		One exact PinMAME ROM set. Many drivers resolve to one machine.
description	string		at least 1 character
year	string		at least 1 character
manufacturer	string		at least 1 character
flags	integer		The PinMAME driver flags for this set, as a bitfield. minimum 0
clone_of	identifier	·	Holds another driver id in this document.
physical_compatibility	enum	·	Compatibility of this ROM driver with the physical machine described by the containing definition. identicalcompatibledifferentunknown
variant_notes	string	·	at least 1 character
display_overrides	display override[]	·	Driver-specific display-layout differences from the canonical physical-machine display inventory. at least 1 item
overrides	device override[]	·

binding

Used byinput.binding,output.binding,device override.binding

Field	Type	Req	Notes
group	identifier		Names the address space. The platform profile says which numbers are legal in it.
device	integer		The number PinMAME reports, not a hardware pin. Negative numbers are real: they carry dedicated and diagnostic inputs from outside the matrix.
channel	integer	·	Only meaningful for an rgb_lamp, which binds one channel per colour. minimum 0

Field

Type

Req

Notes

group

identifier

Names the address space. The platform profile says which numbers are legal in it.

device

integer

The number PinMAME reports, not a hardware pin. Negative numbers are real: they carry dedicated and diagnostic inputs from outside the matrix.

channel

integer

Only meaningful for an rgb_lamp, which binds one channel per colour.

minimum 0

alias

Used byinput.aliases,output.aliases

Field	Type	Req	Notes
namespace	identifier		Which naming system the value belongs to — vpx, pinmame, the operator manual.
value	string		The name that namespace uses for this device. at least 1 character

Field

Type

Req

Notes

namespace

identifier

Which naming system the value belongs to — vpx, pinmame, the operator manual.

value

string

The name that namespace uses for this device.

at least 1 character

provenance

Used bymachineIdentity.playfield.provenance,input.provenance,output.provenance,display.provenance,display override.provenance,mechanism.provenance,relationship.provenance,spatial not applicable.provenance,spatial placement.provenance

Field	Type	Req	Notes
status	assertion state		How well this single assertion is established — not how complete the document is.
source_refs	identifier[]		At least one. An assertion the catalog cannot attribute does not belong in it. Holds source ids. at least 1 item · unique

Field

Type

Req

Notes

status

assertion state

How well this single assertion is established — not how complete the document is.

source_refs

identifier[]

At least one. An assertion the catalog cannot attribute does not belong in it.

Holds source ids.

at least 1 item · unique

input

Used bymachine definition.inputs

Field	Type	Req	Notes
id	identifier		The stable semantic name a table should bind to. If a controller number ever changes, this does not.
label	string		at least 1 character
kind	enum		switchdip_switchconstantvirtual
binding	binding
aliases	alias[]
provenance	provenance
normally_closed	boolean	·	A fact about the real part — an opto conducting at rest, a drop target closed while raised. Build the hardware behaviour; do not convert it into a runtime flip.
pulse	boolean	·	The switch fires its coil directly in copper, so it must act whether or not a game is running.
initial_active	boolean	·	Controller-facing active state that a recreation must establish before starting the game controller; omitted means the definition does not declare a startup state.
availability	enum	·	Whether the exact machine/controller contract uses this input address; this is independent of whether the address represents a physical, virtual, or constant input. usedunusedoptionalunknown
physical	physical	·
spatial	spatial	·
wiring	wiring	·
roles	identifier[]	·	Holds portable role names such as cabinet.start or ball.position. unique
constant_active	boolean	·	Whether a constant or virtual input remains permanently active while the controller runs; omitted means the definition does not declare constant activity.

output

Used bymachine definition.outputs

Field	Type	Req	Notes
id	identifier		The stable semantic name a table should bind to.
label	string		at least 1 character
kind	enum		coilflasherlamprgb_lampgimotorservomagnetrelaycontrol_signalvirtual
binding	binding
aliases	alias[]
provenance	provenance
model	identifier	·	Holds a shared behaviour model.
availability	enum	·	Whether the exact machine/controller contract publishes meaningful state at this output address. A virtual output may be used when it carries runtime state, or unused when it is dead, reserved, or constant-zero address space. usedunusedoptionalunknown
physical	physical	·
spatial	spatial	·
roles	identifier[]	·	Holds portable role names, engine-neutral. unique
wiring	wiring	·
range	object	·	The travel of a servo or other modulated drive.

output.range

Used byoutput.range

Field	Type	Req	Notes
minimum	number
maximum	number
steps	integer	·	minimum 1

display

Used bymachine definition.displays

Field	Type	Req	Notes
id	identifier
label	string		at least 1 character
kind	enum		segmentdmdvideo
provenance	provenance
controller_index	integer	·	Zero-based display-layout index exposed by the controller for this physical display. minimum 0
segment_start	integer	·	Zero-based start position in controller display memory for a segment display, measured in digits. minimum 0
width	integer	·	minimum 1
height	integer	·	minimum 1
spatial	display spatial	·

display override

Used bydriver.display_overrides

Needs at least one of controller_index, segment_start, width and height.

Field	Type	Req	Notes
target	identifier		Holds a display id.
provenance	provenance
controller_index	integer	·	Replacement zero-based controller display-layout index for the target display. minimum 0
segment_start	integer	·	Replacement zero-based controller display-memory start position for the target segment display, measured in digits. minimum 0
width	integer	·	minimum 1
height	integer	·	minimum 1

mechanism

Used bymachine definition.mechanisms

Field	Type	Req	Notes
id	identifier
label	string		at least 1 character
kind	enum		drop_target_bankdivertergatekickermotorizedreelrotarytoyother
actuators	identifier[]		Holds output ids. unique
sensors	identifier[]		Holds input ids. unique
behavior	string		How the assembly acts, in prose: what ejects, what confirms, what state it starts in. at least 1 character
provenance	provenance
assembly_part_number	string	·	at least 1 character
positions	object[]	·	The named states the assembly can be in, and the sensors that report each.

mechanism.positions

Used bymechanism.positions

Field	Type	Req	Notes
id	identifier
label	string		at least 1 character
sensors	identifier[]		Holds input ids. unique
description	string	·	at least 1 character

relationship

Used bymachine definition.relationships

Field	Type	Notes
id	identifier
kind	enum	pulse is the one to watch: the switch fires the coil in hardware, so pops and slings must not wait for the ROM. directnormally_closed_seriesrelay_gatedinvertedpulse
source	identifier	Holds an input id.
destination	identifier	Holds an output id.
provenance	provenance

source

Used bymachine definition.sources

Field	Type	Req	Notes
id	identifier
kind	enum		pinmame_catalogpinmame_corepinmame_simvpe_csharpvpe_scenelegacy_jsonvpx_scriptvpx_tablemanualservice_bulletinservice_diagnosticrom_static_analysisruntime_scenariohuman_review
uri	string		Where the source lives. Never a copy of the source itself — no ROM, manual or table binary is committed. at least 1 character
locator	string		The exact place inside it: page, line range or section. at least 1 character
revision	string	·	at least 1 character
sha256	string	·	Byte identity of the retained artifact. This detects drift in the local copy; it says nothing about what the source contains. Use excerpts for that. pattern ^[0-9a-f]{64}$
excerpts	excerpt[]	·	Transcribed regions of this source that a definition was read out of, so the provenance of an assertion is legible without holding the document. Expected on any source a reader cannot simply open: a local-only manual, a community table, a web page. at least 1 item
license	string	·	at least 1 character
attribution	string	·	at least 1 character
source_id	string	·	at least 1 character
original_filename	string	·	at least 1 character
rights	string	·	at least 1 character
known_working	boolean	·	This table is known to run the real ROM, which is what makes it authoritative on bindings.
acquired_at	string	·	date-time

excerpt

A transcribed region of a source, stored beside the definition. One source normally carries several: a manual is cited separately for its switch table, its lamp table and each schematic sheet. An excerpt is the substrate provenance is read from, not proof of correctness - it is transcribed by the same party making the assertion.

Used bysource.excerpts

Field	Type	Req	Notes
id	identifier
locator	string		Where in the source this region is: page, sheet, drawing number, block. at least 1 character
path	string		Repository-relative path to the transcription, normally under evidence/excerpts/. at least 1 character
sha256	string		pattern ^[0-9a-f]{64}$
image	string	·	Optional rendered crop of the same region, for facts that are drawings rather than tables. Lossless WebP, grayscale unless colour carries meaning. Do not threshold to 1-bit: printed shading is itself evidence on some machines, such as the shaded opto rows of a switch matrix. at least 1 character
image_sha256	string	·	pattern ^[0-9a-f]{64}$
image_derivation	string	·	How the crop was produced, so it can be re-derived from the retained document: page, crop box, dpi, tool and version. at least 1 character
method	enum	·	How the transcription was produced. An excerpt is itself an assertion, so a low-tier OCR pass and a curator-verified read must be distinguishable. manualocrmodelmixed
transcribed_by	string	·	at least 1 character
reviewed	boolean	·	Whether a curator visually checked the transcription against the rendered page.

spatial

one of

Optional spatial evidence for a device or display in the canonical global playfield space: x=0 is left, x=1 is right, y=0 is the rear/backglass end, and y=1 is the front/apron end. This is normalized VPX/player view and is never inferred from physical.location prose.

Used byinput.spatial,output.spatial

One ofspatial located spatial not applicable

spatial located

Used byspatial.one of

Field	Type	Req	Notes
status	enum		candidateobservedvalidatedconflicted
placements	spatial placement[]		at least 1 item

spatial not applicable

Used byspatial.one of

Field	Type	Notes
status	string	not_applicable
reason	enum	unusedvirtualconstantdip_switchcabinet_or_serviceinternal_nonvisualno_physical_device
provenance	provenance

display spatial

value

Displays are cabinet/backbox services, not playfield devices; located playfield display coordinates are unsupported.

Used bydisplay.spatial

spatial placement

Used byspatial located.placements

Field	Type	Notes
id	identifier
role	enum	What the device does at that point: reads the ball, moves it, or lights it. sensoreffectemitter
space	string	playfield
x	number	0 is the left edge of the playfield, 1 the right. minimum 0 · maximum 1
y	number	0 is the rear, at the backglass end; 1 is the front, at the apron. minimum 0 · maximum 1
provenance	provenance

knowledge

Used bymachine definition.knowledge

Field	Type	Req	Notes
path	string		The recreation note beside this definition. pattern ^knowledge/.+\.md$
status	enum		stubpartialcomplete

Field

Type

Req

Notes

path

string

The recreation note beside this definition.

pattern ^knowledge/.+\.md$

status

enum

stubpartialcomplete

physical

Used byinput.physical,output.physical

Field	Type	Req	Notes
part_number	string	·	at least 1 character
assembly_part_number	string	·	at least 1 character
location	string	·	Prose from the manual. Never used to infer coordinates — that is what spatial is for. at least 1 character
quantity	integer	·	minimum 1
switch_type	enum	·	leafmicroswitchoptoreedbuttondiptiltotherunknown
shared_emitter_group	string	·	at least 1 character
emitter_channel	enum	·	bluegreenred
co_located_addresses	integer[]	·	unique
shared_physical_quantity	integer	·	minimum 1
notes	string	·	at least 1 character

wiring

Used byinput.wiring,output.wiring

Field	Type	Req	Notes
board	string	·	at least 1 character
driver_transistor	string	·	at least 1 character
drive_wire	string	·	at least 1 character
drive_connection	string	·	at least 1 character
return_wire	string	·	at least 1 character
return_connection	string	·	at least 1 character
return_component	string	·	at least 1 character
power_wire	string	·	at least 1 character
power_connection	string	·	at least 1 character
control_wire	string	·	at least 1 character
control_connection	string	·	at least 1 character
nominal_voltage_v	number	·	greater than 0
voltage_type	enum	·	acdc

device override

Used bydriver.overrides

Field	Type	Req	Notes
target	identifier		Holds an input or output id.
binding	binding

conflict

Used bymachine definition.conflicts

When status is ignored, rationale is present.

Field	Type	Req	Notes
id	identifier
path	string		Where in the document the sources disagree. at least 1 character
description	string		at least 1 character
source_refs	identifier[]		At least two, since a conflict needs two sides. Holds source ids. at least 2 items · unique
status	enum	·	unresolved (default) means evidence is still needed. ignored means the disagreement is real but cannot affect a recreation, so it does not gate author readiness; it requires a rationale. unresolvedignored
rationale	string	·	Why an ignored conflict cannot affect a recreation. Required when status is ignored, and must contain an ASCII letter or digit. minLength alone accepts a single space; a non-whitespace test still accepts invisibles such as U+200B; and a Unicode letter test still accepts default-ignorable letters such as U+115F. ASCII also keeps this pattern identical under Python re and ECMA-262, where \w disagrees. at least 1 character · pattern [A-Za-z0-9]

Controller profile

One document per controller platform: the address groups a machine on that platform may bind to, the legal numbers in each, and whether the emulator has already normalised polarity.

schemas/controller.schema.json

controller profile

document root

Field	Type	Notes
format	string	Identifies the document type. Always this exact string. pinmame-controller-profile
version	number	1
id	string
authority	string	pinmame
hardware_family	string	at least 1 character
inversion_applied_by_emulator	boolean	Consumers must use the public PinMAME API state as delivered and must not apply another controller-wide inversion. This contract does not claim that every public input is active-high or that every physically normally-closed switch has a nonzero per-game inversion mask; platform and per-game notes preserve mixed-level exceptions. true
groups	group[]	at least 1 item
sources	object[]	at least 1 item

sources

Used bycontroller profile.sources

Field	Type	Notes
uri	string	at least 1 character
revision	string	at least 1 character
locator	string	at least 1 character

address rule

Used bygroup.address_rules

Needs exactly one of minimum and maximum, or values.

Field	Type	Req	Notes
minimum	integer	·
maximum	integer	·
values	integer[]	·	An explicit list, where the legal numbers are not a contiguous range. unique

Field

Type

Req

Notes

minimum

integer

maximum

integer

values

integer[]

An explicit list, where the legal numbers are not a contiguous range.

unique

group

Used bycontroller profile.groups

Field	Type	Req	Notes
id	string		The value a device binding names in its group field.
direction	enum		Which way the data flows across this group. inputcontrolled_deviceconfiguration
kind	enum		switchdip_switchsolenoidlampgi
label	string		at least 1 character
address_rules	address rule[]		at least 1 item
transports	object		How this group reaches the emulator, per integration.
notes	string	·	Technical behavior and exceptions for this controller group. Content is plain text unless notes_format explicitly selects Markdown. at least 1 character
notes_format	enum	·	How notes is rendered by catalog consumers. Omit this field or use plain_text for literal prose. Use markdown only for reviewed GitHub Flavored Markdown, start nested headings at level 4, and do not embed raw HTML; consumers must escape raw HTML, reject unsafe link and image URL schemes, and keep headings at level 4 or deeper. plain_textmarkdown

group.transports

Used bygroup.transports

Field	Type	Req	Notes
libpinmame	object	·
controller_plugin	object	·

group.transports.libpinmame

Used bygroup.transports.libpinmame

Field	Type	Req	Notes
channel	enum		switchsolenoidlampgidip

group.transports.controller_plugin

Used bygroup.transports.controller_plugin

Field	Type	Req	Notes
group_id	integer		minimum 0
contract_revision	string		pattern ^[0-9a-f]{40}$

Something wrong or missing?

Changing the schema changes this page — it is generated from the files themselves on every deploy. Adding a field means adding it to schemas/machine.schema.json and to the validator that enforces it.

Cite a source for anything you change — a manual page, a line in a working VPX script, PinMAME source, or a reading from the machine's own service menu. Claims without provenance cannot be validated.

Read the guide Report a problem

Before you startCONTRIBUTING.md schemas/machine.schema.json docs/MACHINE_DEFINITIONS_PLAN.md How to read a definition