Football incident attributes

Some incidents carry more detail than their name. A Goal is not just "Goal" - it can be an own goal, a penalty, scored with the left foot from outside the box, under high pressure, with no goalkeeper in front of it. That detail arrives as attributes[] on the incident's definition in GET /v2/sports/{id}, and it is what the per-sport data reference already renders under each incident that has any.

The shape

On the sport definition, not on a match:

{
  "id": 413,
  "name": "Goal",
  "attributes": [
    { "id": 397, "name": "Own goal", "short_name": "own-goal", "sort_order": 1 },
    { "id": 398, "name": "Penalty goal", "short_name": "penalty-goal", "sort_order": 2 }
  ]
}

sort_order is a flat display order, not a semantic grouping - own goal and penalty goal get orders 1 and 2, but so does an unrelated attribute three groups later. There is no field on the attribute that says which of "Goal type", "Placement", or "Technique of shot" it belongs to.

What is generated, what is curated

Layer	Source	Freshness
Attribute id and name	GET /v2/sports/{id}, same as every other table on the data reference	always current - generated on every build
Semantic group label ("Goal type", "Placement"...)	data/reference/annotations/incident-attribute-groups.json, migrated from API/Football Incident Attributes Reference	curated, football only, partial

Football's incidents render their attributes grouped under these labels on the Soccer data reference page. An attribute with no curated group still renders - under a plain Other heading - instead of silently disappearing. Every other sport's incidents render their attributes the same ungrouped way, since no one has curated groups for them yet.

The Confluence version was already stale, not just incomplete

Before wiring this up as generated data, the attribute ids in API/Football Incident Attributes Reference (v1.1) were checked against the live definition. Two kinds of drift, not one:

• Same meaning, different id. Error's two attributes are 944/945 in the document, 895/896 in production. Copying the document's ids would have pointed at attributes that no longer exist.
• Missing entirely. Possible VAR has 3 live attributes, the document lists 5 - two were removed. Yellow card has 10 live "reason" attributes (Handball, Diving, Tactical foul...) and Red card has 6 more - none of them are in the document at all. Goal has 4 live attributes for how the move started (Open play, Fast break, Set piece, No assist) that are also absent.

A hand-copied table would have been wrong on the ids and missing the single most useful group for a trading use case - why a card was given - on day one. Generating the id/name list removes that failure mode entirely; only the group label can now go stale, and it fails visibly (as "Other"), not silently (as a wrong id).

Reading it in practice

Match incidents (events_incidents on GET /v2/events/{id}, or important-incidents - see time, clocks and timezones for which one to use) carry the attribute ids that actually happened on a given incident, as a plain array. Resolve each id against the sport definition's incidents[].attributes[] - the same table rendered on the data reference - to get its name and group.

Next

• Soccer data reference - the generated, grouped table itself
• Show a match timeline - where incidents appear on a real match