Markdown helps a person and an AI understand a job. JSON helps software exchange the answer without guessing what each sentence means.

JSON stands for JavaScript Object Notation. The name sounds technical, but the idea is simple: JSON is a predictable way to label information. An application can read it, store it, send it to another service, and know where each piece belongs.

Read this before you worry about writing it

Here is JSON describing one company:

{
  "ticker": "MGM",
  "company_name": "MGM Resorts International",
  "as_of_date": "2026-09-11",
  "revenue_growth_percent": 7.4,
  "has_positive_free_cash_flow": true,
  "risk_flags": ["high debt"],
  "sources": [
    {
      "title": "Quarterly filing",
      "url": "https://example.com/filing"
    }
  ]
}

You can understand most JSON by learning five ideas.

The punctuation is doing organization work. Curly brackets hold an object. Square brackets hold a list. A colon connects a label to its value. A comma separates one item from the next.

The types of information JSON can hold

JSON has a small vocabulary:

{
  "text": "A sentence is a string",
  "number": 42,
  "decimal": 7.4,
  "yes_or_no": true,
  "unknown": null,
  "list": ["one", "two"],
  "group": { "inside": "another object" }
}

Use strings for text. Use numbers for things you may calculate or compare. Use true and false for a real yes-or-no state. Use null when a value is genuinely missing—not when you want the system to make something up.

Why JSON matters in an AI project

The moment AI starts using tools, APIs, databases, or multiple agents, it needs a reliable format for passing information around.

User inputApplicationModel or agentJSON resultDatabaseUser interfaceNext agent

If an agent returns a paragraph saying, “Revenue seems good,” another system cannot safely graph it, compare it, filter it, or check the source. If it returns a number, a date, a confidence field, and a source record in known locations, the system can work with it.

JSON is not a replacement for judgment

Structured data does not automatically make data correct. A JSON file can contain a wrong number as neatly as a spreadsheet can. It is still your job to decide:

• what fields matter
• where facts come from
• which values require a source
• how recent the information must be
• what an agent should do when it cannot verify a value

Sonariq is a useful example. Its research instructions can be written in Markdown because they explain how to investigate a company. The results can be structured so a later step can distinguish the ticker, date, financial figures, source links, risks, and unresolved questions.

Sonariq: Markdown instructions generate structured handoffs

Sonariq does not ask one AI to write a vague research essay and hope the next AI understands it. It breaks the work into stages. Each stage has a PROMPT.md file that tells the agent what job it owns, what evidence it must inspect, what standards apply, and what it must leave behind for the next stage.

For example, a research stage may read these human-readable Markdown files:

README.md                         — how the whole research workflow works
Shared_Standards.md               — evidence, sourcing, and quality rules
Data_Contracts.md                 — the fields and file shapes the system expects
03_Financial_Data_and_Modeling_Handoff/PROMPT.md
                                  — the job for this specific stage

The agent then creates two different kinds of output. The first is readable: a HANDOFF.md that explains what it found, what changed, what is uncertain, what was tested, and what the next analyst must do. The second is machine-readable: JSON files that tell the rest of the system exactly where the work lives and whether it can be used.

PROMPT.md: instructions and research methodResearch agentShared standards + data contractsHANDOFF.md: findings, decisions, open workStage_Manifest.json: inputs, outputs, statusArtifact_Index.json: exact artifact locationsStructured research data: JSON / CSVNext analyst

Here is the shape of a small stage manifest. The real Sonariq version can be more detailed, but the point is simple: software can see the stage, its inputs, its outputs, and whether the work is ready to continue.

{
  "run_id": "us-casinos-2026-09-11",
  "stage_id": "03_financial_data_and_modeling_handoff",
  "company_key": "mgm-resorts",
  "status": "COMPLETE_WITH_LIMITATIONS",
  "inputs": [
    "companies/mgm-resorts/02_qualitative/v001/HANDOFF.md",
    "project/Research_Charter.md"
  ],
  "outputs": [
    "companies/mgm-resorts/03_financials/v001/Financials_Normalized.csv",
    "companies/mgm-resorts/03_financials/v001/HANDOFF.md"
  ],
  "next_stage": "04_model_and_valuation_builder"
}

That is what we mean when we say an MD file can generate a JSON handoff. The Markdown file does not magically turn itself into JSON. It gives the agent a durable, reviewed assignment. The agent follows that assignment and writes structured records that the next agent, the application, and the human reviewer can all use.

The handoff is stronger because both files exist:

This pattern matters well beyond equity research. A content pipeline can use a Markdown brief and JSON content record. A customer-support agent can use a Markdown policy and JSON ticket result. A software agent can use SPEC.md and return JSON test results. Markdown directs the work; JSON makes the result operational.

The three JSON mistakes beginners make

1. Missing a comma. Every item in an object or array needs a comma except the last one. 2. Using the wrong quotation marks. JSON requires straight double quotes around keys and text values. 3. Mixing prose and data. Keep a number as a number. Keep an explanation in its own text field. Do not bury both in one long sentence.

You do not need to hand-write every JSON document. AI can generate it and editors can validate it. You need enough understanding to recognize the shape of the information and notice when something is missing.

Practical exercise: structure a product record

Take one product or business you know. Write a JSON object with its name, category, price, website, and three features.

{
  "name": "",
  "category": "",
  "price_per_month": 0,
  "website": "",
  "features": []
}

Ask an AI: “Check whether this is valid JSON. Then tell me which fields I would need if I wanted users to search and compare these products.”

JSON in the real world: what else can it do?

JSON is not only for configuration files and API responses. Open a section when you want to understand what the format is doing inside a real product or AI workflow.

Database records and exports+

What it is: A database stores individual records—users, products, articles, research runs, or orders—as named fields. JSON is a common shape for moving those records into or out of the database.

Example: A product export might carry a name, price, category, image URL, stock count, and tags so another application can import the same catalog.

AI structured outputs+

What it is: Instead of asking a model for an unstructured paragraph, you require a known set of fields. This lets the result drive software without someone manually extracting the answer.

Example: A research agent returns ticker, thesis, risks, sources, and confidence as separate fields. Your app can show risks in one area and sources in another.

Data contracts+

What it is: A data contract is the agreement about what one part of a system gives another: field names, types, required values, and what missing data means.

Example: Sonariq's data contracts tell each research stage how to identify an artifact, record its version, and show whether it is complete, limited, or blocked.

Tool and API definitions+

What it is: A tool needs a precise menu of inputs before an AI can call it safely. JSON describes the tool name, its arguments, and the shape of the result.

Example: A get_company_filing tool can require a ticker and filing type, then return a JSON object with the filing URL, date, and extracted facts.

Agent memory and job state+

What it is: Agents need a compact record of where a task stands: completed steps, current variables, tool results, and the next action. JSON is ideal because a program can read and update it reliably.

Example: An overnight research run stores stage: 4, completed: true, next_stage: 5, and a list of artifact paths. The next session starts from the state rather than guessing.

RAG documents and metadata+

What it is: Retrieval systems split documents into searchable chunks. JSON often holds the useful labels around each chunk: document ID, title, author, date, source URL, tags, and location.

Example: When an AI retrieves a paragraph from an earnings filing, metadata lets it show the exact filing and page rather than presenting an unsupported answer.

Content systems and media generation+

What it is: Websites and content pipelines use structured records for articles, products, images, video settings, and publishing status.

Example: A post record can include title, slug, hero_image, excerpt, author, tags, and published_at. A site can turn those fields into a page automatically.

Authentication and permissions+

What it is: Applications pass structured identity information between services so they know who a user is and what that user may access.

Example: A session payload can identify a user ID and role such as admin, editor, or member, allowing the app to show the right controls.

Front-end application state+

What it is: Interactive websites and apps constantly track form values, selected filters, saved preferences, feature flags, translations, and chart data. JSON gives the interface a consistent state to render.

Example: A stock screener can store selected sectors, market-cap range, sort order, and the current page as structured state instead of trying to interpret text.

Test fixtures and expected results+

What it is: Builders keep known sample inputs and expected outputs so they can test whether a feature still works after a change.

Example: A login test can load a JSON user record and expect a JSON response that includes a session but never exposes a password.

Analytics events+

What it is: Products record what people do: page views, signups, clicks, purchases, errors, and campaign attribution. Each event needs consistent fields so it can be counted and compared.

Example: A signup event can contain the page, campaign, device type, timestamp, and anonymous visitor ID. Analytics software can then answer which campaign produced real signups.

Deployment and cloud tooling+

What it is: Build tools, cloud platforms, package managers, and serverless functions use JSON to describe dependencies, settings, and deployment behavior.

Example: A package.json file lists a web project's dependencies and scripts, so another developer—or Codex—can install and run it the same way.

Design systems+

What it is: A design system can keep its colors, type sizes, spacing, borders, and component variations as reusable JSON tokens.

Example: One JSON value for the brand green can be used by the website, mobile app, charts, and generated marketing assets without everyone manually choosing a slightly different green.

Financial research and scoring+

What it is: Research systems need facts that can be compared, ranked, charted, and checked. JSON keeps each figure and its context in a reliable place.

Example: Sonariq can carry normalized company facts, financial-series data, citation metadata, scoring inputs, and report status forward between research stages. Markdown still carries the reasoning that explains what those fields mean.

Check your understanding

1. What is the difference between an object and an array? 2. Why is 42 different from "42"? 3. When should a missing value be null rather than an invented estimate? 4. Why would an application prefer structured JSON to a paragraph when saving a research result?