Это полный информационный перевод нормативного оригинала на английском, сверенный с ревизией репозитория 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Оригинал соответствует редакции профиля точного времени 0b87c52c6ef999286c745e19998fdfcd03d5dbee, SHA-256 26aa5da029278939f914e578107242d9607d4f2dc5fe153272b82f9ed1030101. Перевод предназначен для чтения человеком и не становится новой редакцией спецификации. При расхождении требований нормативным остаётся оригинал. Английская версия для чтения содержит тот же документ с навигацией и стабильными якорями разделов.

Это временной профиль instant-0b87c52: stale_after задаёт абсолютный момент времени. Профиль календарной даты, соответствующий редакции 3fcbb9f828c2f23d109c855ee403c3a4c81f3a96, — отдельная редакция, которая также называется OKF 0.2.

В переводе ОБЯЗАТЕЛЬНО и ДОЛЖНЫ передают REQUIRED и MUST; НЕ ДОЛЖНЫ — MUST NOT; СЛЕДУЕТ — SHOULD; МОГУТ и МОЖЕТ — MAY. Имена полей, типов, значимые для обработки заголовки примеров (# Computation, # Citations) и исполняемый код сохранены.

Open Knowledge Format (OKF)

Версия 0.2

OKF — открытый формат, удобный для людей и агентов. Он описывает знания: метаданные, контекст и отобранные полезные сведения о данных и системах. Формат рассчитан на документы, которые люди пишут, агенты создают, организации передают друг другу, а люди и агенты читают.

Формат намеренно прост: каталог файлов Markdown с блоками метаданных YAML в начале каждого файла. Нет реестра схем, центрального управляющего органа или обязательных инструментов. Если вы можете выполнить cat для файла, вы можете прочитать OKF; если можете выполнить git clone для репозитория, можете передать его другим.

Документ самодостаточен: он определяет всё необходимое для создания и чтения OKF v0.2. Изменения относительно v0.1 перечислены в §13.

1. Мотивация

Способы представления знаний для AI-агентов быстро развиваются, и появляются многочисленные несовместимые соглашения. OKF исходит из того, что знания лучше представлять в общедоступных, устоявшихся форматах, которые:

Всё чаще корпус знаний создаётся не один раз для последующего чтения: агенты непрерывно пишут и поддерживают его. Когда большинство понятий создают машины, читателю нужны ответы на вопросы, которые обычное соглашение «Markdown с метаданными» явно не выделяет:

  1. Из чего это создано и как проверено? (Происхождение.)
  2. Насколько этому можно доверять? (Доверие.)
  3. Верно ли это до сих пор? (Актуальность.)
  4. Это текущая версия? (Жизненный цикл.)
  5. Получено ли это число предписанным способом? (Аттестация вычисления.)

OKF v0.2 явно описывает происхождение, доверие, жизненный цикл и аттестацию, сохраняя минимум предписаний. Формат задаёт минимум правил. Он стандартизирует только небольшой набор структурных соглашений, нужных для самоописания корпуса знаний; остальные решения остаются за создателем.

Цели

  1. Определить универсальный формат, в который создатели — люди, агенты и процессы экспорта — могут записывать знания.
  2. Объяснить, как читатели — агенты, интерфейсы, поисковые индексы и детерминированный код — должны читать документы и переходить между ними.
  3. Облегчить обмен знаниями между системами и организациями.
  4. Стандартизировать небольшой набор полей метаданных, который позволяет оценивать доверие к корпусу, поддерживаемому агентами, без требования конкретной среды исполнения.

Что не входит в цели

2. Термины

3. Структура набора

Набор — дерево каталогов с файлами Markdown. Структура каталогов не зависит от предметной области: создатели организуют понятия так, как удобно для описываемых знаний.

path/to/bundle/
  index.md                      # Необязательно. Список содержимого для постепенного знакомства.
  log.md                        # Необязательно. Хронологическая история обновлений.
  <concept>.md                  # Понятие в корне набора.
  <subdirectory>/               # Подкаталоги объединяют понятия в группы.
    index.md
    <concept>.md
    <subdirectory>/
      ...

Набор МОЖЕТ распространяться как:

3.1 Зарезервированные имена файлов

Следующие имена имеют заданное значение на любом уровне иерархии и НЕ ДОЛЖНЫ использоваться для документов понятий:

Имя файла Назначение
index.md Список содержимого каталога. См. §8.
log.md История обновлений. См. §9.

Все остальные файлы .md — документы понятий.

Теги явно представлены полем метаданных tags (§4.1). OKF не задаёт отдельного формата файла для объединения документов по тегу. Если читателю нужен просмотр по тегам, он может построить его при чтении, просканировав метаданные.

4. Документы понятий

Каждое понятие — файл Markdown в кодировке UTF-8, состоящий из двух частей:

  1. Начальный блок метаданных YAML, начинающийся строкой --- в начале файла и заканчивающийся отдельной строкой ---.
  2. Тело Markdown с содержимым произвольной формы.

4.1 Начальный блок метаданных

---
type: <Имя типа>                  # ОБЯЗАТЕЛЬНО
title: <Необязательное отображаемое имя>
description: <Необязательное краткое описание в одну строку>
resource: <Необязательный канонический URI описываемого объекта>
tags: [<тег>, <тег>, ...]          # Необязательно
# ... поля происхождения, доверия, жизненного цикла и вычислений (см. §5, §10)
# ... другие пары ключ/значение, определённые создателем
---

Обязательные поля:

type — единственный ключ, обязательный всегда; понятие только с полем type полностью соответствует формату (§11).

Рекомендуемые поля:

Также могут присутствовать необязательные группы полей происхождения, доверия и жизненного цикла (§5), а у понятий типа Attested Computation — поля вычисления (§10).

Расширения: создатели МОГУТ добавлять любые ключи. Читателям СЛЕДУЕТ сохранять неизвестные ключи при чтении с последующей записью и они НЕ ДОЛЖНЫ отвергать документы с неизвестными полями.

4.2 Тело документа

Тело — стандартный Markdown. Создателям СЛЕДУЕТ предпочитать структурированный Markdown — заголовки, списки, таблицы и блоки кода с ограждением — свободной прозе, поскольку структура облегчает и чтение человеком, и поиск агентами.

Обязательных разделов тела нет. Следующие заголовки имеют общепринятое значение, и их СЛЕДУЕТ использовать, когда это уместно:

Заголовок Назначение
# Schema Структурированное описание столбцов или полей объекта.
# Examples Конкретные примеры использования, часто в блоках кода с ограждением.
# Computation Утверждённое вычисление понятия Attested Computation. См. §10.

Для ссылки на внешний источник отдельного утверждения используются сноски Markdown, связанные с записями sources, а не список цитат в теле (§5.1).

4.3 Пример: понятие, связанное с ресурсом

---
type: BigQuery Table
title: Заказы клиентов
description: Одна строка на каждый завершённый заказ клиента по всем каналам.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
---

# Схема

| Столбец       | Тип       | Описание |
|---------------|-----------|----------|
| `order_id`    | STRING    | Глобально уникальный идентификатор заказа. |
| `customer_id` | STRING    | Внешний ключ в [таблицу клиентов](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Сумма заказа в долларах США. |
| `placed_at`   | TIMESTAMP | Время отправки заказа клиентом. |

# Соединения

Соединяется с [таблицей клиентов](/tables/customers.md) по `customer_id`.

4.4 Пример: понятие без привязки к ресурсу

---
type: Playbook
title: "Реагирование на инцидент: предупреждение об актуальности данных"
description: Шаги диагностики предупреждения об актуальности данных в обработке заказов.
tags: [oncall, incident]
generated: { by: human:ahormati, at: 2026-04-12T09:00:00Z }
---

# Условие запуска

Предупреждение об актуальности возникает, когда данные `orders` отстают
более чем на 30 минут от ожидаемого SLA. См. [таблицу заказов](/tables/orders.md).

# Шаги

1. Проверьте [панель задания загрузки](https://example.com/dash).
2. ...

5. Происхождение, доверие и жизненный цикл

Эти группы полей позволяют ответить на вопросы «откуда это взялось», «насколько этому доверять» и «актуально ли это» по метаданным. Все они необязательны. Их отсутствие имеет значение: непроверенное понятие отличается от проверенного, но никогда не отвергается (§11).

Каждый ключ OKF со значением времени содержит дату и время ISO 8601 с явно заданным смещением UTC, например 2026-06-30T14:00:00Z.

5.1 Происхождение: sources

sources перечисляет материалы внутри или вне набора, из которых получено понятие.

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: Схема экспорта GA4 в BigQuery
    author: team:ga4-docs
    usage_count: 5000
    last_modified: 2026-05-30T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }

Каждая запись sources содержит:

Признаки надёжности источника. OKF записывает объективные признаки каждого источника, чтобы читатель мог оценивать доверие к понятию по источникам, из которых оно получено. Оценка надёжности не хранится: она субъективна, не переносится между читателями и устаревает. Надёжность выводится из признаков, как и уровни доверия (§5.3), а не хранится. Каждый признак необязателен и записывается в запись sources:

usage_count — приблизительный признак. Его можно сравнивать на уровне «используется или не используется», порядка величины и с историей самого источника, но нельзя использовать как точный рейтинг между разными видами источников: выполнения запроса по расписанию и намеренные просмотры панели человеком имеют разный вес. Читателям СЛЕДУЕТ воспринимать это поле как признак использования и тенденции, а не итоговую оценку.

Цепочка происхождения выражается ссылками, а не отдельным полем. Когда resource указывает на другое понятие OKF, связь происхождения уже присутствует в графе набора (§6), поэтому читатель МОЖЕТ рекурсивно изучать sources источника и распространять оценку надёжности по цепочке. Внешние конечные источники несут только собственные признаки. Более глубокая цепочка происхождения — явное внешнее derived_from или происхождение данных — выходит за рамки v0.2.

Привязка отдельного утверждения к источнику. Для конкретного утверждения используйте сноску Markdown, метка которой совпадает с sources[].id:

Таблица `events_` разбивается по дням на `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: Схема экспорта GA4 в BigQuery

Метка сноски — ключ связи с sources. Читатели определяют источник по соответствующей записи, а не разбирают текст сноски. Метки задаются ключами, а не позициями (sources[0]), поскольку агенты постоянно переписывают документы: при перестановке списка позиционный индекс незаметно связывает утверждение с неверным источником, а стабильный id сохраняет связь.

5.2 Доверие: generated и verified

generated описывает, как создано текущее содержимое. verified записывает, кто или что подтвердило содержимое относительно его источников или resource. Поля разделены, поскольку тот, кто написал понятие, не обязательно является тем, кто его подтвердил.

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }

verified:
  - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }

verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }

5.3 Уровни доверия

Читатели выводят уровень доверия из verified, от низшего к высшему:

Понятие без метаданных доверия по-прежнему можно читать; читатели НЕ ДОЛЖНЫ его отвергать (§11). Уровни доверия — рекомендательные признаки, а не управление доступом.

5.4 Жизненный цикл: status

status: stable        # draft | stable | deprecated

Отсутствующий status ⇒ stable.

5.5 Жизненный цикл: stale_after

stale_after: 2026-09-23T00:00:00Z   # содержимое устаревает в этот момент или позднее

Необязательное поле. Абсолютный момент времени. Понятие считается устаревшим при now >= stale_after. Абсолютный момент, в отличие от относительного TTL, позволяет принимать решение об устаревании простым сравнением без обращения ко времени чтения понятия.

6. Связи и пути

Понятия МОГУТ ссылаться друг на друга стандартными ссылками Markdown. Поддерживаются две формы:

Ссылка от понятия A к понятию B утверждает наличие связи. Её конкретный вид — родитель/потомок, ссылка на источник, соединение или зависимость — задаётся окружающим текстом, а не самой ссылкой. Читатели, строящие граф, обычно считают все ссылки направленными рёбрами связи без типа.

Читатели ДОЛЖНЫ допускать неработающие ссылки: ссылка на отсутствующую цель в наборе не является некорректной; она может обозначать ещё не записанное знание.

6.2 Поля со значением пути

Несколько полей содержат путь или URI: resource, sources[].resource, computation, executor.resource и attester.resource (§10). Вместо пути sources[].resource может содержать описание области (§5.1). Каждое поле со значением пути принимает:

6.3 Соглашение о references/

Подкаталог references/ по соглашению содержит копии внешних материалов, инструкции запуска или код как полноценные понятия внутри набора. Источники, исполнители и проверяющие часто ссылаются на него, например на references/attesters/revenue.py. Это соглашение об именовании, а не требование.

7. Соглашение об участниках действия

Поля, записывающие личность или идентичность (generated.by, verified[].by), используют единое соглашение:

Читатели, определяющие уровень доверия (§5.3), используют префикс human:, поэтому создатели ДОЛЖНЫ применять его для содержимого, написанного или подтверждённого человеком.

8. Файлы оглавления

Файл index.md МОЖЕТ находиться в любом каталоге, включая корень набора. Он перечисляет содержимое каталога и позволяет постепенно знакомиться с набором: человек или агент видит доступные материалы перед открытием отдельных документов.

Файлы оглавления не содержат начального блока метаданных, кроме одного исключения: index.md в корне набора МОЖЕТ содержать ключ okf_version (§12). Тело состоит из одного или нескольких разделов, каждый из которых объединяет понятия под заголовком:

# Заголовок раздела / группы

* [Название 1](relative-url-1) - краткое описание элемента 1
* [Название 2](relative-url-2) - краткое описание элемента 2

# Другой раздел

* [Подкаталог](subdir/) - краткое описание подкаталога

Записям СЛЕДУЕТ включать описание из метаданных понятия, на которое они ссылаются. Создатели МОГУТ автоматически формировать index.md; читатели МОГУТ создавать его при чтении, когда он отсутствует.

9. Файлы журнала

Файл log.md МОЖЕТ находиться на любом уровне иерархии и хранить историю изменений соответствующей области. Формат — плоский список записей, сгруппированных по датам, сначала новые:

# Журнал обновлений каталога

## 2026-05-22
* **Обновление**: Добавлено описание таблицы BigQuery [Метрики клиентов](/tables/customer-metrics.md).
* **Создание**: Подготовлена [инструкция Dataplex](/playbooks/dataplex.md).

## 2026-05-15
* **Инициализация**: Создана базовая структура каталогов.

Заголовки дат ДОЛЖНЫ иметь форму ISO 8601 YYYY-MM-DD. Записи журнала — проза; первое выделенное жирным слово (**Update**, **Creation**, **Deprecation** — «обновление», «создание», «вывод из использования») — соглашение, а не требование.

10. Понятие аттестуемого вычисления

Понятие Attested Computation описывает не только то, что означает значение, но и утверждённый способ его вычисления. Это позволяет читателю подтвердить, что агент выполнил утверждённое вычисление, а не придумал своё. Происхождение (§5.1) отвечает на вопрос «откуда взялось это утверждение»; аттестация — «получено ли это число предписанным способом». OKF записывает вычисление и средства его проверки; сам формат ничего не выполняет.

10.1 Вычисление — самостоятельное понятие

Утверждённое вычисление — отдельное понятие с type: Attested Computation. Понятие, которому нужно значение, например Metric или BigQuery Table, ссылается на него обычной ссылкой Markdown (§6). Отдельное понятие нужно по трём причинам:

10.2 Поля контракта

Контракт задаётся полями верхнего уровня в начальном блоке метаданных понятия. Помимо происхождения, доверия и жизненного цикла (§5), понятие Attested Computation содержит:

Что именно стоит за resource — навык (Skill), скрипт или контейнер — вопрос упаковки. OKF фиксирует интерфейс, а не упаковку (§1).

---
type: Attested Computation
title: Выручка за финансовый год
description: Признанная выручка за финансовый год по определению финансового отдела.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Политика признания выручки
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

Вычисление связывает только объявленные `parameters` согласно политике признания.[^rev-policy]

[^rev-policy]: Политика признания выручки

10.3 Вычисление

Задайте вычисление одним из двух способов:

runtime: bigquery
computation: references/computations/lib/revenue.sql
parameters:
  - { name: year, type: integer, required: true }

Агент МОЖЕТ задавать только значения объявленных parameters; он НЕ ДОЛЖЕН писать или редактировать вычисление. Читатель отвечает за привязку значений параметров к computation и формирование исполняемого результата. Проверяющий независимо повторяет ту же привязку и сравнивает её с тем, что действительно выполнялось. Поскольку сравнивается развёрнутый, скомпилированный результат из свидетельства (executed_sql, compiled_sql), переписанный запрос, подменённый файл вычисления или изменённая зависимость не проходят проверку. Типизированный интерфейс, позволяющий задавать только параметры, превращает вопрос «выполнялось ли утверждённое вычисление» в механическое сравнение вместо субъективного суждения.

10.4 Понятия, использующие вычисление

Документ редко описывает только одно вычисление. Обзор отчёта о финансовых результатах, рассматривающий выручку, прибыль и маржу, остаётся одним читаемым понятием и ссылается на отдельное Attested Computation для каждого показателя:

---
type: Metric
title: Выручка
description: Признанная выручка за финансовый год.
tags: [finance, revenue]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
---

# Определение

Признанная выручка — сумма `amount` по строкам, учтённым за финансовый год;
её рассчитывает [вычисление выручки](../computations/revenue.md).

Поскольку каждое вычисление — отдельное понятие, выручка может оставаться актуальной, когда прибыль уже прошла stale_after; каждое аттестуется по собственному запуску. Совместное размещение определяется каталогами — например, папкой computations/ с index.md, — а не метаданными.

10.5 Использование читателем (информационный раздел)

Этот подраздел информационный, а не нормативный. Описанные ниже результаты исполнения не хранятся в наборе.

  1. Обнаружение через type: Attested Computation: признак в метаданных можно включить в index.md. Читатель открывает понятие непосредственно или переходит по ссылке из понятия, которое его использует.
  2. Загрузка контракта из метаданных и вычисления из тела либо файла, названного в computation.
  3. Параметризация: агент задаёт значения объявленных параметров.
  4. Выполнение: исполнитель запускает вычисление с привязанными значениями и возвращает свидетельство в форме executor.receipt.
  5. Аттестация: читатель запускает проверяющего для свидетельства. Проверка подтверждает происхождение — выполненное вычисление совпадает с computation, привязанным к заявленным параметрам, а не с SQL, написанным агентом, — и точность — отображаемое значение совпадает с авторитетным источником из свидетельства, повторно прочитанным по идентификатору задания, а не взятым из текста агента.
  6. Допуск результата: отказ от отображения при неуспешной аттестации; предупреждение или отказ при now >= stale_after. При успехе показать вердикт, например ссылку на журнал задания, чтобы основания доверия были видны.

10.6 Проверка определения и аттестация запуска

verified (§5.2) и аттестация различаются; нужны обе:

Понятие с устаревшим определением всё ещё может успешно пройти аттестацию, а недавно проверенное определение по-прежнему требует аттестации каждого запуска. Поэтому нужны обе проверки.

11. Соответствие формату

Набор соответствует OKF v0.2, если:

  1. Каждый файл .md без зарезервированного имени в дереве содержит начальный блок метаданных YAML, который можно разобрать.
  2. Каждый блок метаданных содержит непустое поле type.
  3. Каждый присутствующий файл с зарезервированным именем (index.md, log.md) следует структуре §8 и §9 соответственно.

При наличии групп полей доверия, жизненного цикла, происхождения или вычисления создателям СЛЕДУЕТ следовать §5–§10, а читатели:

Читателям СЛЕДУЕТ считать все остальные ограничения мягкими рекомендациями. В частности, читатели НЕ ДОЛЖНЫ отвергать набор из-за:

12. Версионирование

Этот документ определяет OKF версии 0.2. Версии имеют вид <major>.<minor>:

Наборы МОГУТ объявлять поддерживаемую версию через okf_version: "0.2" в начальном блоке метаданных корневого index.md — единственном месте, где в index.md допускаются метаданные. Читателям, не понимающим заявленную версию, СЛЕДУЕТ попытаться прочитать набор в меру своих возможностей вместо отказа.

Рассмотрено и отложено

Следующие вопросы намеренно оставлены будущей редакции:

13. Изменения относительно v0.1

v0.2 заменяет OKF v0.1 и является увеличением минорной версии согласно §12, кроме двух намеренных несовместимых изменений ниже: они переименовывают или выводят из использования поля v0.1. Читатель v0.2 может читать набор v0.1 с описанными здесь вариантами совместимости.

13.1 Несовместимые изменения

13.2 Добавления

Всё перечисленное ниже — добавления: новые необязательные ключи, один новый тип понятия и один новый общепринятый заголовок. Их отсутствие оставляет обычное понятие v0.1.

Всё остальное — структура набора, зарезервированные имена файлов, обязательный type, рекомендуемые title/description/resource/tags, ссылки между понятиями, файлы оглавления, журналы, мягкие правила соответствия — перенесено без изменений.

Приложение A: полный пример отчёта о финансовых результатах

Один набор, использующий все группы полей, показан как переход с v0.1 на v0.2 для отчёта о финансовых результатах с двумя показателями: выручкой и валовой прибылью.

Форма v0.1

Один документ: оба показателя в одном понятии; SQL в тексте, который агент может прочитать, проигнорировать или переписать; цитаты плоским списком; единственная временная отметка — timestamp.

---
type: Metric
title: Отчёт о финансовых результатах (финансовый год)
description: Основные показатели отчёта о финансовых результатах за финансовый год.
tags: [finance, income-statement]
timestamp: '2026-05-28T22:53:05+00:00'
---

# Определение
Отчёт о финансовых результатах содержит выручку и валовую прибыль за финансовый год.

# Выручка
Признанная выручка — сумма `amount` по строкам, учтённым за финансовый год:

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = <year>

# Валовая прибыль
Валовая прибыль по сегментам согласно стандарту распределения затрат:

    SELECT gross_profit FROM fct_income_statement
    WHERE fiscal_year = <year> AND segment = <segment>

# Citations
- https://wiki.acme/finance/fpa-handbook
- https://wiki.acme/finance/revenue-recognition
- https://wiki.acme/finance/cost-allocation

Форма v0.2

Два показателя выделены в аттестуемые вычисления, на которые ссылается описательное понятие. Заполнены все группы полей; два вычисления намеренно имеют разные состояния, поэтому один читатель получает два разных вердикта.

bundles/finance/
  metrics/income-statement.md      type: Metric  (описывает, ссылается на оба)
  computations/revenue.md          type: Attested Computation  (runtime: bigquery)
  computations/profit.md           type: Attested Computation  (runtime: dbt)
  references/skills/run-on-bq.md, run-dbt.md
  references/attesters/sql-equality.py, dbt-binding.py

metrics/income-statement.md — читаемый документ; основания доверия к вычислениям находятся в понятиях, на которые он ссылается, а не здесь:

---
type: Metric
title: Отчёт о финансовых результатах (финансовый год)
description: Основные показатели отчёта о финансовых результатах за финансовый год.
tags: [finance, income-statement]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: fpa-handbook
    resource: https://wiki.acme/finance/fpa-handbook
    title: Руководство FP&A по отчётности
---

# Определение
Отчёт о финансовых результатах содержит [выручку](../computations/revenue.md)
и [валовую прибыль](../computations/profit.md) за финансовый год согласно
руководству FP&A по отчётности.[^fpa-handbook] Каждый показатель получается
утверждённым вычислением, допускающим аттестацию; это понятие только описывает их.

[^fpa-handbook]: Руководство FP&A по отчётности

computations/revenue.md — SQL BigQuery, проверенный человеком, актуальный и подтверждённый используемой панелью с признаками надёжности источника:

---
type: Attested Computation
title: Выручка за финансовый год
description: Признанная выручка за финансовый год по определению финансового отдела.
tags: [finance, revenue]
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/sql-equality.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-28T14:00:00Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Политика признания выручки
    author: team:finance-fpa
    last_modified: 2026-04-02T00:00:00Z
  - id: exec-rev-dash
    resource: dashboards/exec-revenue
    title: Панель выручки для руководства
    author: team:finance-fpa
    usage_count: 5000
    last_modified: 2026-06-18T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

Признанная выручка согласно политике признания,[^rev-policy] подтверждённая
панелью выручки для руководства.[^exec-rev-dash]

[^rev-policy]: Политика признания выручки
[^exec-rev-dash]: Панель выручки для руководства

computations/profit.md — модель dbt, проверенная процессом и уже прошедшая свой stale_after:

---
type: Attested Computation
title: Валовая прибыль за финансовый год
description: Валовая прибыль по сегментам за финансовый год согласно стандарту распределения затрат.
tags: [finance, profit]
status: stable
runtime: dbt
parameters:
  - { name: year, type: integer, required: true }
  - { name: segment, type: string, required: true }
executor:
  resource: references/skills/run-dbt.md
  receipt: [run_id, compiled_sql, result]
attester:
  resource: references/attesters/dbt-binding.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-14T14:00:00Z }
verified: { by: process:finance-nightly, at: 2026-06-12T08:00:00Z }
stale_after: 2026-06-15T00:00:00Z
sources:
  - id: cost-alloc
    resource: https://wiki.acme/finance/cost-allocation
    title: Стандарт распределения затрат
---

# Computation

    SELECT gross_profit
    FROM {{ ref('fct_income_statement') }}
    WHERE fiscal_year = {{ var('year') }}
      AND segment = {{ var('segment') }}

Валовая прибыль по сегментам согласно стандарту распределения затрат.[^cost-alloc]

[^cost-alloc]: Стандарт распределения затрат