IRI в проекте Проводник

iurii-epaneshnikov · 16.Июнь.2025 05:15:16

IRI (Internationalized Resource Identifier) — это интернационализированная версия URI, которая идентифицирует ресурс в семантическом вебе (например: http://graph.system-school.ru/L3/Система).

Многое в проекте «Проводник по персональному маршруту» строится вокруг графа знаний, поэтому необходимо обеспечить простой доступ к информации, содержащейся в нём, в частности — к понятиям. Это позволяет использовать данные из графа не только для генерации руководств, но и в личных образовательных целях, переписке и других сценариях.

Также IRI служит дополнительной защитой от дублирования понятий, поскольку в нашей системе не может существовать двух одинаковых IRI.

Про IRI и как это работает:

IRI - просто стандарт для адресов с Unicode (типа …/система). Это не программа, а правила записи.
Nginx ловит запрос, настраивается так:

Разбирает адрес (даже с русскими буквами)
Перенаправляет в GraphQL (как прокси)

GraphQL ищет данные:

В графе есть узлы с полем iri (например, concept.iri = “…/система”)
Ищет по этому полю (как поиск по ID)
Возвращает найденное Nginx’у

Nginx смотрит заголовок Accept и отдаёт:

Браузеру - HTML
Программе - JSON
Или другой формат

Как именно GraphQL ищет:

В Neo4j это обычный поиск по полю (как WHERE iri = “…”
В GraphDB (если RDF) - ищет по subject с этим IRI

Важно:

IRI преобразуется в HTTP-запросе (русские буквы → %D1%81…)
Но в базе хранится оригинальный IRI

`Accept` заголовок	Формат ответа
`text/html`	HTML (для людей)
`application/json`	JSON (API)
`application/ld+json`	JSON-LD (Linked Data)
`text/turtle`	Turtle (RDF)

Как будет выглядеть запрос и ответ в контексте проекта “Проводник по персональному маршруту”

http://graph.system-school.ru/L3/система

GET /L3/система HTTP/1.1
Host: graph.system-school.ru
Accept: application/json`

{
  "@context": {
    "@vocab": "https://schema.org/",
    "kb": "http://graph.system-school.ru/#",
    "name_ru": "kb:name_ru",
    "name_en": "kb:name_en",
    "conceptType": "kb:conceptType",
    "relatedConcepts": {
      "@id": "kb:relatedConcept",
      "@type": "@id"
    },
    "examples": {
      "@id": "kb:hasExample",
      "@type": "@id"
    }
  },
  "@id": "http://graph.system-school.ru/L3/система",
  "@type": "DefinedTerm",
  "name_ru": "Система",
  "name_en": "System",
  "purpose": "Описание совокупности элементов, взаимодействующих для достижения цели",
  "conceptType": "Фундаментальное понятие",
  "usageContext": "Научные дисциплины, инженерия, менеджмент, кибернетика",
  "synonyms": ["Комплекс", "Совокупность", "Организация"],
  "definition_ru": "Совокупность взаимосвязанных элементов, образующих целостность и единство, обладающая свойствами, не присущими отдельным элементам",
  "definition_en": "A set of interconnected components that form an integrated whole with emergent properties",
  "summary": "Целостный комплекс элементов с взаимосвязями и эмерджентными свойствами",
  "example": "Ножницы. Имеют способность резать материалы (не присуща отдельным лезвиям)",
  "promptHint": "Используйте при описании простых структур с взаимозависимыми элементами",
  "difficulty": 3,
  "bloom": "Analyse",
  "version": "1.2",
  "relatedConcepts": [
    {
      "@id": "http://graph.system-school.ru/L3/элемент_системы",
      "relation": "состоит из",
      "name_ru": "Элемент системы"
    },
    {
      "@id": "http://graph.system-school.ru/L3/эмерджентность",
      "relation": "проявляет свойство",
      "name_ru": "Эмерджентность"
    }
  ],
  "examples": [
    {
      "@id": "http://graph.system-school.ru/example/1",
      "kind": "positive",
      "text": "Кровеносная система человека: органы взаимодействуют для транспорта крови"
    },
    {
      "@id": "http://graph.system-school.ru/example/2",
      "kind": "negative",
      "text": "Набор случайных предметов на столе не образует систему без функциональных связей"
    }
  ],
  "disciplines": [
    {
      "name": "Системное мышление",
      "level": "meta"
    },
    {
      "name": "Кибернетика",
      "level": "meta-meta"
    }
  ]
}

Ответ для браузера:

<html lang="ru">
<head>
    <meta charset="UTF-8">
    <title>Система - System School Knowledge Graph</title>
    <script type="application/ld+json">
    {
      "@context": {
        "@vocab": "https://schema.org/",
        "kb": "http://graph.system-school.ru/#",
        "name_ru": "kb:name_ru",
        "name_en": "kb:name_en",
        "conceptType": "kb:conceptType",
        "relatedConcepts": {
          "@id": "kb:relatedConcept",
          "@type": "@id"
        },
        "examples": {
          "@id": "kb:hasExample",
          "@type": "@id"
        }
      },
      "@id": "http://graph.system-school.ru/L3/система",
      "@type": "DefinedTerm",
      "name_ru": "Система",
      "name_en": "System",
      "purpose": "Описание совокупности элементов, взаимодействующих для достижения цели",
      "conceptType": "Фундаментальное понятие",
      "usageContext": "Научные дисциплины, инженерия, менеджмент, кибернетика",
      "synonyms": ["Комплекс", "Совокупность", "Организация"],
      "definition_ru": "Совокупность взаимосвязанных элементов, образующих целостность и единство, обладающая свойствами, не присущими отдельным элементам",
      "definition_en": "A set of interconnected components that form an integrated whole with emergent properties",
      "summary": "Целостный комплекс элементов с взаимосвязями и эмерджентными свойствами",
      "example": "Ножницы. Имеют способность резать материалы (не присуща отдельным лезвиям)",
      "promptHint": "Используйте при описании простых структур с взаимозависимыми элементами",
      "difficulty": 3,
      "bloom": "Analyse",
      "version": "1.2",
      "relatedConcepts": [
        {
          "@id": "http://graph.system-school.ru/L3/элемент_системы",
          "relation": "состоит из",
          "name_ru": "Элемент системы"
        },
        {
          "@id": "http://graph.system-school.ru/L3/эмерджентность",
          "relation": "проявляет свойство",
          "name_ru": "Эмерджентность"
        }
      ],
      "examples": [
        {
          "@id": "http://graph.system-school.ru/example/1",
          "kind": "positive",
          "text": "Кровеносная система человека: органы взаимодействуют для транспорта крови"
        },
        {
          "@id": "http://graph.system-school.ru/example/2",
          "kind": "negative",
          "text": "Набор случайных предметов на столе не образует систему без функциональных связей"
        }
      ],
      "disciplines": [
        {
          "name": "Системное мышление",
          "level": "meta"
        },
        {
          "name": "Кибернетика",
          "level": "meta-meta"
        }
      ]
    }
    </script>
    <style>
        body { font-family: Arial, sans-serif; line-height: 1.6; max-width: 900px; margin: 0 auto; padding: 20px; }
        header { border-bottom: 2px solid #eee; margin-bottom: 20px; }
        h1 { color: #2c3e50; }
        h2 { color: #3498db; border-bottom: 1px solid #eee; padding-bottom: 5px; }
        .example { padding: 10px; margin: 10px 0; border-radius: 5px; }
        .positive { background-color: #e8f5e9; border-left: 4px solid #4caf50; }
        .negative { background-color: #ffebee; border-left: 4px solid #f44336; }
        .property { margin-bottom: 10px; }
        .property-name { font-weight: bold; color: #2c3e50; }
        footer { margin-top: 30px; padding-top: 10px; border-top: 1px solid #eee; font-size: 0.9em; color: #7f8c8d; }
    </style>
</head>
<body>
    <header>
        <h1>Система (System)</h1>
        <p>IRI: <a href="http://graph.system-school.ru/L3/система">http://graph.system-school.ru/L3/система</a></p>
        <p class="property">
            <span class="property-name">Тип понятия:</span> 
            <span>Фундаментальное понятие</span>
        </p>
    </header>

    <section>
        <h2>Основные свойства</h2>
        <div class="property">
            <span class="property-name">Назначение:</span> 
            <span>Описание совокупности элементов, взаимодействующих для достижения цели</span>
        </div>
        <div class="property">
            <span class="property-name">Контекст использования:</span> 
            <span>Научные дисциплины, инженерия, менеджмент, кибернетика</span>
        </div>
        <div class="property">
            <span class="property-name">Синонимы:</span> 
            <span>Комплекс, Совокупность, Организация</span>
        </div>
    </section>

    <section>
        <h2>объяснение</h2>
        <div class="property">
            <span class="property-name">Русское объяснение:</span> 
            <blockquote>Совокупность взаимосвязанных элементов, образующих целостность и единство, обладающая свойствами, не присущими отдельным элементам</blockquote>
        </div>
        <div class="property">
            <span class="property-name">English definition:</span> 
            <blockquote>A set of interconnected components that form an integrated whole with emergent properties</blockquote>
        </div>
        <div class="property">
            <span class="property-name">Пример:</span> 
            <span>Ножницы. Имеют способность резать материалы (не присуща отдельным лезвиям)</span>
        </div>
    </section>

    <section>
        <h2>Характеристики</h2>
        <div class="property">
            <span class="property-name">Сложность:</span> 
            <span>3/5 (для специалистов)</span>
        </div>
        <div class="property">
            <span class="property-name">Уровень по Блуму:</span> 
            <span>Анализ (Analyse)</span>
        </div>
        <div class="property">
            <span class="property-name">Подсказка для использования:</span> 
            <span>Используйте при описании простых структур с взаимозависимыми элементами</span>
        </div>
    </section>

    <section>
        <h2>Связанные понятия</h2>
        <ul>
            <li><a href="http://graph.system-school.ru/L3/элемент_системы">Элемент системы</a> (состоит из)</li>
            <li><a href="http://graph.system-school.ru/L3/эмерджентность">Эмерджентность</a> (проявляет свойство)</li>
        </ul>
    </section>

    <section>
        <h2>Примеры</h2>
        <div class="example positive">
            <h3>✅ Правильное использование</h3>
            <p>Кровеносная система человека: органы взаимодействуют для транспорта крови</p>
        </div>
        <div class="example negative">
            <h3>❌ Неправильное использование</h3>
            <p>Набор случайных предметов на столе не образует систему без функциональных связей</p>
        </div>
    </section>

    <section>
        <h2>Дисциплины</h2>
        <ul>
            <li>Системное мышление (уровень: meta)</li>
            <li>Кибернетика (уровень: meta-meta)</li>
        </ul>
    </section>

    <footer>
        <p>Версия данных: 1.2 | Источник: System School Knowledge Graph</p>
    </footer>
</body>
</html>