Настоящий раздел содержит техническую документацию, предназначенную для специалистов в области информационных технологий и разработки программного обеспечения.

Спецификация партнёрского источника данных (Partner Data Endpoint) v1.1.1

Дата: 2026-01-26  |  Статус: Стабильная версия

Содержание

Введение

Это техническая спецификация источника данных (Data Endpoint) — точки доступа к данным в формате связанных данных (Linked Data), которую должны реализовать партнёрские организации для интеграции с экосистемой Граф филармоний.

Архитектура: граф-ориентированный программный интерфейс с навигацией по ссылкам (Graph-native Hypermedia API)

Граф филармоний использует граф-ориентированную архитектуру, которая объединяет:

Это позволяет ИИ-агентам и приложениям автоматически обнаруживать и навигировать по всем данным организации.

Принцип работы

Федеративная архитектура с двойным присутствием:

  1. Партнёрская организация хранит все свои данные в собственной базе данных
  2. Партнёр реализует Data Endpoint по данной спецификации и выбирает базовый путь для размещения
  3. Централизованный реестр Граф филармоний периодически синхронизируется с партнёрским источником данных
  4. Реестр хранит только метаданные (ссылки, статусы, дата синхронизации)
  5. Полные данные остаются у партнёра и всегда актуальны

Универсальность источника данных

Data Endpoint — это единая точка доступа к данным организации для всех потребителей:

Базовый путь эндпоинтов

Партнёр самостоятельно выбирает базовый путь для размещения Data Endpoint.

Рекомендуемые варианты

Вариант 1: Папка /id/ (рекомендуется)

https://{partner-domain}/id/

Примеры:

Вариант 2: Папка /data/

https://{partner-domain}/data/

Вариант 3: Поддомен

https://data.{partner-domain}/

Требования к базовому пути

Slash URIs — формат идентификаторов

В версии 1.1 все @id являются разыменовываемыми URL (Slash URIs):

✅ Правильно (Slash URI):

{
  "@id": "https://filarmonia.online/id/organization.jsonld",
  "@type": "PerformingGroup",
  "name": "Пермская краевая филармония"
}

❌ Устарело (Hash URI):

{
  "@id": "https://filarmonia.online#organization"
}

Преимущества Slash URIs

Формат @id для разных сущностей

Сущность Формат @id
Организация https://{domain}/{base}/organization.jsonld
Площадка https://{domain}/{base}/places/{uuid}.jsonld
Событие https://{domain}/{base}/events/{uuid}.jsonld
Исполнитель https://{domain}/{base}/performers/{uuid}.jsonld

Формат данных

Каждый ресурс должен содержать блок links для навигации:

{
  "@id": "https://filarmonia.online/id/organization.jsonld",
  "@type": "PerformingGroup",
  "name": "Пермская краевая филармония",

  "links": [
    {
      "rel": "self",
      "href": "https://filarmonia.online/id/organization.jsonld"
    },
    {
      "rel": "places",
      "href": "https://filarmonia.online/id/places.jsonld",
      "title": "Все залы организации"
    },
    {
      "rel": "events",
      "href": "https://filarmonia.online/id/events.jsonld",
      "title": "Все события организации"
    },
    {
      "rel": "performers",
      "href": "https://filarmonia.online/id/performers.jsonld",
      "title": "Исполнители организации"
    }
  ]
}

Стандартные значения rel

rel Описание
selfСсылка на текущий ресурс
alternateАльтернативное представление (HTML-страница)
collectionСсылка на коллекцию (список)
organizationСсылка на организацию
placesСсылка на список залов
eventsСсылка на список событий
performersСсылка на список исполнителей
performerСсылка на конкретного исполнителя
specСсылка на спецификацию

UUID и Slug — идентификаторы

UUID (обязательное поле)

Все сущности должны иметь поле uuid (уникальный идентификатор записи) в теле JSON-LD:

{
  "@id": "https://filarmonia.online/id/organization.jsonld",
  "@type": "PerformingGroup",
  "uuid": "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
  "name": "Пермская краевая филармония"
}

Формат: UUID v4 (случайный)

Генерация:

// JavaScript
const uuid = crypto.randomUUID();

// PHP
$uuid = \Ramsey\Uuid\Uuid::uuid4()->toString();

Slug (опциональное поле)

Slug (читаемый идентификатор в адресной строке) — необязательное дополнение к UUID для поисковой оптимизации:

{
  "uuid": "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
  "slug": "permskaya-filarmonia"
}

Использование:

Обязательный эндпоинт

Для регистрации в централизованном реестре достаточно одного источника данных — профиля организации.

GET /{base}/organization.jsonld Обязательный

Назначение: Получение полного профиля организации

Пример запроса:

GET https://filarmonia.online/id/organization.jsonld

Ответ (200 OK):

{
  "@context": [
    "https://schema.org",
    "https://id.filarmonia.online/spec/1.1/context.jsonld"
  ],
  "@type": "PerformingGroup",
  "@id": "https://filarmonia.online/id/organization.jsonld",
  "uuid": "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
  "slug": "permskaya-filarmonia",

  "orgType": "philharmonia",
  "name": "Пермская краевая филармония",
  "legalName": "ГКБУК «Пермская краевая филармония»",
  "url": "https://filarmonia.online",

  "description": "Ведущее концертное учреждение Прикамья, основанное в 1936 году.",
  "foundingDate": "1936-07-01",

  "logo": "https://filarmonia.online/logo.png",

  "address": {
    "@type": "PostalAddress",
    "streetAddress": "ул. Сибирская, 11",
    "addressLocality": "Пермь",
    "addressRegion": "Пермский край",
    "postalCode": "614015",
    "addressCountry": "RU"
  },

  "telephone": "+7 (342) 212-91-23",
  "email": "office@kf.perm.ru",

  "sameAs": [
    "https://vk.com/filarmoniaperm",
    "https://t.me/filarmoniaperm"
  ],

  "links": [
    {"rel": "self", "href": "https://filarmonia.online/id/organization.jsonld"},
    {"rel": "alternate", "href": "https://filarmonia.online/about/", "type": "text/html"}
  ]
}
Важно: Для культурных организаций используйте @type": "PerformingGroup" вместо Organization.

Опциональные эндпоинты

Следующие эндпоинты реализуются по желанию партнёра в зависимости от возможностей и потребностей.

GET /{base}/health.jsonld Опционально

Назначение: Сервисный источник данных для мониторинга и обнаружения ресурсов

{
  "@context": ["https://schema.org", "https://id.filarmonia.online/spec/1.1/context.jsonld"],
  "@type": "WebAPI",
  "name": "Пермская краевая филармония Data API",
  "status": "healthy",
  "version": "1.1",
  "timestamp": "2026-01-26T10:30:00+05:00",
  "links": [
    {"rel": "organization", "href": "https://filarmonia.online/id/organization.jsonld"}
  ]
}

GET /{base}/places.jsonld Опционально

Назначение: Список площадок (залов) организации

{
  "@context": [
    "https://schema.org",
    "https://id.filarmonia.online/spec/1.1/context.jsonld"
  ],
  "@type": "ItemList",
  "numberOfItems": 2,
  "itemListElement": [
    {
      "@type": "MusicVenue",
      "@id": "https://filarmonia.online/id/places/7c9e6679-7425-40de-944b-e07fc1f90ae7.jsonld",
      "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Большой зал",
      "maximumAttendeeCapacity": 820
    }
  ],
  "links": [
    {"rel": "self", "href": "https://filarmonia.online/id/places.jsonld"},
    {"rel": "organization", "href": "https://filarmonia.online/id/organization.jsonld"}
  ]
}

GET /{base}/events.jsonld Опционально

Назначение: Получение списка событий (концертов, спектаклей)

Параметры (опциональные):

Пример запроса:

GET https://filarmonia.online/id/events.jsonld?from=2026-01-01&limit=10

GET /{base}/performers.jsonld Опционально

Назначение: Получение списка исполнителей (персоны и коллективы)

Поле additionalType для исполнителей

@type additionalType Описание
PersonConductorДирижёр
PersonSoloistСолист
PersonComposerКомпозитор
PersonMusicianМузыкант
MusicGroupOrchestraОркестр
MusicGroupChoirХор
MusicGroupEnsembleАнсамбль
MusicGroupBandГруппа

Обработка ошибок

Коды ответов

Формат ошибки

{
  "@context": "https://schema.org",
  "@type": "Error",
  "statusCode": 404,
  "error": "Not Found",
  "message": "Event with uuid 'abc123' not found",
  "timestamp": "2026-01-23T10:30:00+05:00"
}

Требования

Производительность

Безопасность

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Кеширование

Cache-Control: public, max-age=3600
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Рекомендуемое время кеша:

Краткая справка по эндпоинтам

Источник данных Статус Описание
/{base}/organization.jsonld Обязательный Профиль организации (главная точка входа)
/{base}/health.jsonld Опционально Источник данных для мониторинга
/{base}/places.jsonld Опционально Список площадок
/{base}/places/{uuid}.jsonld Опционально Площадка по UUID
/{base}/events.jsonld Опционально Список событий
/{base}/events/{uuid}.jsonld Опционально Событие по UUID
/{base}/performers.jsonld Опционально Исполнители
/{base}/performers/{uuid}.jsonld Опционально Исполнитель по UUID

Чек-лист перед публикацией

Минимальные требования (для реестра)

Дополнительно (для расширенной интеграции)

Инструменты валидации

  1. Онлайн-валидатор JSON-LD: https://json-ld.org/playground/
  2. Валидатор Schema.org (международного словаря описания данных): https://validator.schema.org/

Примеры тестовых запросов

# Получение профиля организации (обязательный endpoint)
curl https://filarmonia.online/id/organization.jsonld

# Опционально: проверка health
curl https://filarmonia.online/id/health.jsonld

# Опционально: события с фильтром
curl "https://filarmonia.online/id/events.jsonld?from=2026-01-01&limit=10"

# Опционально: исполнители типа Person
curl "https://filarmonia.online/id/performers.jsonld?type=person"

Поддержка

Документация: https://id.filarmonia.online/spec/1.1/

Контакты: https://id.filarmonia.online/contact/

Версия документа: 1.1.1  |  Последнее обновление: 2026-01-26
© 2025-2026 Граф филармоний. Открытый стандарт.