---
title: "Why JSON Analysis Contracts Need Versioning and Validation"
slug: "versioned-analysis-json-contract"
language: "en"
tags: ["분석 데이터 계약","아키텍처 노트","sag 기술","플랫폼 운영"]
created: "2026-10-06T08:00:00.000Z"
published: "2026-10-08T10:17:24.205Z"
updated: "2026-10-08T10:17:29.371Z"
sample: false
---

# Why JSON Analysis Contracts Need Versioning and Validation

## What Is an Analysis Data Contract?

**It is a design for assigning field meanings, versions, and validation rules to JSON observation and reporting data.** This note considers analysis data contracts in terms of the responsibilities of inputs, transformations, and outputs rather than as feature names. To trust an analysis result, it must be possible to trace what data came in, what was checked, and how far the conclusions can go.

## Why Is This Technology Needed?

Even when new engines are easy to add, changes in field meaning can distort historical data. Flexible storage does not mean no validation.

## Design Principles and Data Flow

Validate types, sizes, required values, periods, and versions at input. Distinguish the original data from the transformation version used for aggregation, and preserve missing values in legacy data.

> **Original input** → **Version and field validation** → **Monthly aggregation contract**

Each stage must not describe the success of the previous stage as an achievement of the next. Recording data identifiers, periods, and validation status together makes it possible to locate where omissions and errors occurred and determine what needs to be checked again.

## Connection to the SAG Architecture

SAG reads stored monthly reports and observations according to schema, period, and target criteria. It aggregates citations only when completeness indicators and original records are available.

SAG’s operational value lies in connecting these relationships to pages and questions, comparison results, and improvement tasks. Rather than reading only numbers, customers can review both what needs to be supplemented and the grounds for the assessment. Patterns that require further application should be interpreted according to the scope of the relevant paragraph.

## Illustrative Example and Decision Criteria

If `citations` is absent from illustrative legacy data but is changed to an empty array, “unverified” becomes “no citations.” Transformations by version must preserve the unknown state.

The example above is provided to explain structure and calculations; it is not measured performance data from a particular customer. In an actual report, the selected period, target, observation conditions, and original records must be linked so that the same assessment can be checked again.

## Practical Validation Checklist

| Flow stage | Items to check |
| --- | --- |
| Original input | Check document version and required values |
| Version and field validation | Length and item limits |
| Monthly aggregation contract | Preserve missing values in legacy data |

Check that meanings remain consistent not only for valid inputs, but also for empty data, duplicate data, and data with different conditions. Linking validation items to completion criteria can reduce the gap between feature descriptions and actual operations.

## Limitations and Points to Consider in Application

JSON storage alone does not complete the contract. Validation by readers, as well as migration and regression data, is also needed.

## Research and Official Documentation

- [PostgreSQL JSON Types](https://www.postgresql.org/docs/current/datatype-json.html) — Official documentation describing the characteristics and constraints of JSON storage types.

External resources provide background on the design topics above; they do not certify every SAG implementation or customer outcome. The application guidance and illustrative examples in this note are based on SAG’s operational structure. Source checked: 2026-10-06.

## Further Reading and Feature Information

- [Related architecture note](/ko/blog/citation-completeness-denominator)
- [Try a service connected to the analysis data contract](/ko/preview/geo?scenario=cream)
- [Feature-specific FAQ](/en/faq)
- [Discuss implementation scope](/ko#inquiry)


## How to Explore This Technology Further

Explore tenant permissions, job retries, caches, and approval history.

- [Designing stable customer spaces](/ko/blog?tag=%ED%94%8C%EB%9E%AB%ED%8F%BC%20%EC%9A%B4%EC%98%81)
- [Feature guide FAQ](/en/faq)