Data Visibility & Public Access

Visibility is enforced at the API layer through a three-tier filter: public, member and sensitive. A @public decorator marks endpoints that an unauthenticated spectator can hit; everything else requires a principal. For each resource a PublicFieldConfig defines which fields are public by default, with admin CRUD over the configuration and an effective-view endpoint that shows the merged result of platform defaults plus tenant overrides. Scope_type tags differentiate global open data (world rankings, FIPJP federation directory, generic rules) from national open data (per-federation rankings, results, calendars, club and district directories), so a public reader on petanque.life sees the global view while a national federation site filters to its own scope_code.

For player records the model is more granular. PrivacySettings is embedded in PlayerProfile and lets the player toggle profile-visible, show-club, show-date-of-birth, show-ranking and show-results. The public-players endpoint enforces these flags before serialising any field. Sensitive fields are gated by SensitiveFieldRule with required_capability — for example reading a player's date of birth needs profile:read_dob, license number needs profile:read_license_number, contact details need profile:read_contact — so a club secretary sees more than a spectator without the visibility logic being scattered across handlers. The /player-profiles/{id}/visible-fields endpoint returns exactly what the calling principal can read, which the apps use to render forms without dead fields.

The open-data layer is its own product surface. GET /public/open-data exposes a catalogue of fourteen public endpoints — calendar, competitions, rankings, results, federation directory, venues — with cursor pagination on every list endpoint and a federation_code filter for nationally-scoped queries. The calendar is also delivered as an RFC 5545 iCalendar feed at /public/calendar/ical so external tools can subscribe. SEO is handled at /public/seo/sitemap.xml with federation, club, competition, venue and ranking pages, plus JSON-LD structured data (SportsOrganization, SportsEvent, Event, SportsActivityLocation) and Open Graph metadata so search engines and social platforms render rich previews.