Asset Notation

asset-notation

Asset Notationのリファレンス実装です。これは、時間の経過に伴う所有資産と負債を記述するオープンフォーマットです。

役割は3つあります。ドキュメントが有効かどうかを判定し、既存のスプレッドシートとの間で数値をやり取りし、マシン上のAIアシスタントにドキュメントを提供します。

npx asset-notation validate portfolio.json
npx asset-notation from-csv accounts.csv > portfolio.json
npx asset-notation to-csv   portfolio.json > accounts.csv
npx asset-notation mcp      wealth.json

import { validate, fromCsv, toCsv } from 'asset-notation';

const doc = fromCsv(readFileSync('accounts.csv', 'utf8'));
const { valid, errors, notes } = validate(doc);

CSV 対応がある理由

仕様を試すために口座情報を再入力する人はいません。既存の数値を取り込めないフォーマットは使い始められないため、ここでのコンバーターは単なる便利機能ではなく、入り口です。

1行が1つの保有資産とその最新評価額を表します。これは誰もがすでに使っている形式です。口座ごとの行に、名前、残高、日付を記載します。

英語圏以外のオフィスでも使えるかどうかを左右する点が2つあります。どちらも、説明で済ませるのではなく、実際に対応しています。

• フランス語、ドイツ語、スペイン語の Excel で保存したスプレッドシートでは、列がセミコロンで区切られ、小数点にはコンマが使われます。 コンマ区切りとして読み込むと、4210,55 が2つの列になり、残高がすべて壊れてしまいます。区切り文字はヘッダーから判定し、見つかった区切り文字に基づいて金額を読み取ります。
• 金額は最初から最後まで文字列のまま扱います。 残高が浮動小数点数によって丸められることはありません。

桁区切りは削除されます。スプレッドシートで使われるノーブレークスペースも対象です（1 234,56 と 1,234.56 はどちらも 1234.56 になります）。日付も同様に読み取ります。24/06/2026 と 24.06.2026 は日／月／年、06/24/2026 は月／日／年として扱われ、どちらの形式とも解釈できる場合は区切り文字によって判定します。

AI アシスタントから使う

asset-notation mcp <file.json> は、stdio 経由で動作するModel Context Protocolサーバーです。アシスタントがファイルを読み取り、管理します。データがマシンの外に出ることはなく、ネットワークも使用しません。ファイルが存在しない場合は、最初の保有資産を追加するときに作成されます。

アシスタントのデスクトップアプリ、または任意の MCP クライアントの設定ファイルで、mcpServers の下に次のように記述します。

{
	"mcpServers": {
		"wealth": { "command": "npx", "args": ["-y", "asset-notation", "mcp", "/home/you/wealth.json"] }
	}
}

汎用 MCP クライアントでも同じ設定を使えます。コマンドは npx、引数は -y asset-notation mcp /home/you/wealth.json、トランスポートは stdio です。パスは絶対パスにしてください。クライアントはシェルを介さずにコマンドを起動するため、~ は展開されません。

ツール：read_document、net_worth、list_holdings、upsert_holding、add_valuation、validate、import_csv。リソース：asset-notation://document。書き込みのたびにドキュメント全体を検証し、無効な場合はエラーを示して拒否します。ファイルは全体を書き換え、インデントはスペース2つ、金額は文字列のまま保持します。net_worth は各保有資産の最新評価額を正確に合算して通貨ごとに1行で表示し、使用した評価額のうち最も古い日付も示します。

AI に誰かの資産管理を頼む場合

このパッケージは、Asset Notation 形式の JSON ファイルを1つ読み書きします。このファイルには、holdings（口座、不動産、ローンなど。各項目は asset または liability）、institutions、および金額を小数の文字列で記録した日付付きの valuations が含まれます。npx -y asset-notation mcp <file.json> で起動し、list_holdings を呼び出して、add_valuation で評価額を記録し、net_worth で回答します。すべてマシン上に保持され、状態を保存するのはこのファイルだけです。書き込みの前に、付属のスキーマに照らして検証されます。

検証

使用するスキーマは、文書が宣言するバージョンの major.minor に基づいて選択されます。文書自身が何であるかを示し、それに照らして判定されます。スキーマはパッケージ内に含まれているため、検証にネットワークもレジストリも必要ありません。これは、フォーマット自体が求めている性質と同じです。

スキーマに加えて、JSON Schema では表現できない文書レベルのルールがあります。

状況	判定
1 つのコレクション内で同じ id が 2 回使われている	エラー
parentId の連鎖が自分自身に戻ってくる	エラー
1 つの保有資産に対する同じ主体の所有権行が、期間内で重複している	エラー
存在しないものを指す参照	注記、有効なまま
1 つの保有資産の所有権割合の合計が 1 を超えている	注記、有効なまま

未解決の参照は意図的なものであり、重要な点です。有効な文書の任意の部分集合も有効です。そのため、12 件の口座のうち 3 件を対象とし、記述対象に含まれていない銀行の名前を挙げる文書は、正当な部分開示であり、壊れたファイルではありません。これをエラーとして報告すれば、このフォーマットが存在する目的である共有そのものを禁じることになります。

validate() は不正な文書に対して例外をスローしません。問題点を報告することがその役割です。

仕様の適合性コーパス（conformance/。バージョンごとに 1 ファイルがあり、スキーマと同様に逐語的にミラーされています）はテストスイートで実行されます。各ケースには、このバリデーターが到達すべき判定が記されているため、ライブラリと仕様が気づかないうちに乖離することはありません。

API

validate(doc: unknown): {
  valid: boolean;
  schemaVersion: string | null;
  errors: string[];   // what makes it invalid
  notes: string[];    // true, and not a fault
}

supportedVersions(): string[]

toCsv(doc, { delimiter? }): string
fromCsv(text, { delimiter?, generatedAt?, version?, baseCurrency? }): Document

netWorth(doc): {
  byCurrency: { currency, assets, liabilities, net }[];  // decimal strings
  oldestAsOf: string | null;
  unvaluedHoldingIds: string[];
  valuedHoldings: number;
}

fromCsv は時計を読み取るのではなく generatedAt を受け取るため、同じ入力からは常に同じバイト列が生成されます。これにより、変換したファイルを diff で比較したり、コミットしたりできます。

終了コード

0 は有効、1 は無効、2 はコマンドに誤りがあることを示します。診断メッセージは stderr に、結果は stdout に出力されるため、警告を読み取れる状態に保ちながら変換結果をパイプで渡せます。

ライセンス

仕様と同じ Apache-2.0 です。