# IMI法人種別抽出コンポーネント

JSON-LD に含まれる「表記を持つ法人型」の表記を解析して、
組織種別・組織種別位置を付与するライブラリです。
コマンドラインツールおよび WebAPI サーバも提供されます。

# 利用者向け情報

## インストール

適当な作業フォルダを作成しモジュールをインストールします。

```
$ mkdir work
$ cd work
$ npm install imi-enrichment-hojin-1.0.0.tgz
```

## API

モジュール imi-enrichment-hojin は以下のような API の関数です。

```
module.exports = function(jsonld) {..}
```

- jsonld : 変換対象となる JSON-LD オブジェクト


# 使用例

以下の手順では enrich 関数によって input (JSON) から output (JSON) に変換され、
結果が標準出力に出力されます。

```main.js
const enrich = require('imi-enrichment-hojin');

const input = {
  "@context": "https://imi.go.jp/ns/core/context.jsonld",
  "@type": "法人型",
  "表記": "株式会社ほげほげ"
};

const output = enrich(input);

console.log(JSON.stringify(output,null,2));
```

実行すると以下のような出力が得られます。

```
$ node main.js
{
  "@context": [
    "https://imi.go.jp/ns/core/context.jsonld",
    "http://hojin-info.go.jp/ns/domain/biz/1/context.jsonld"
  ],
  "@type": "法人型",
  "表記": "株式会社ほげほげ",
  "組織種別位置": "前",
  "組織種別": {
    "@type": "コード型",
    "識別値": "301",
    "表記": "株式会社"
  },
  "メタデータ": {
    "@type": "hj:更新履歴型",
    "hj:更新者": {
      "@type": "実体型",
      "表記": "IMI法人種別抽出コンポーネント"
    },
    "種別": "INFO",
    "説明": "プロパティ(組織種別|組織種別位置) が追加されました。",
    "日時": {
      "@type": "日時型",
      "標準型日時": "2019-02-08T20:08:01.350+09:00"
    }
  }
}
$
```

## コマンドラインツールとしての利用

コマンドラインツールの実体は `bin/cli.js` です。
指定されたひとつのファイルまたは標準入力に含まれる JSON をパースして
変換結果を標準出力に出力します。

以下は動作確認用ファイル `example/simple.json` を変換する事例です。

```
$ npm install imi-enrichment-hojin-1.0.0.tgz
$ cd node_modules/imi-enrichment-hojin
$ node bin/cli.js example/simple.json
{
  "@context": [
    "https://imi.go.jp/ns/core/context.jsonld",
    "http://hojin-info.go.jp/ns/domain/biz/1/context.jsonld"
  ],
  "@type": "法人型",
  "表記": "株式会社ほげほげ",
  "組織種別位置": "前",
  "組織種別": {
    "@type": "コード型",
    "識別値": "301",
    "表記": "株式会社"
  },
  "メタデータ": {
    "@type": "hj:更新履歴型",
    "hj:更新者": {
      "@type": "実体型",
      "表記": "IMI法人種別抽出コンポーネント"
    },
    "種別": "INFO",
    "説明": "プロパティ(組織種別|組織種別位置) が追加されました。",
    "日時": {
      "@type": "日時型",
      "標準型日時": "2019-02-08T20:09:24.912+09:00"
    }
  }
}
$
```

動作確認用ファイルは以下の３つです。

- example/simple.json : 単一のインスタンスをもつ JSON-LD
- example/graph.json : ３つのインスタンスをもつ JSON-LD
- example/line-delimited.json.txt : 1行ごとに独立した JSON-LD が記録された Line delimited JSON

なお、入力形式が Line delimited JSON と判定された場合には、
出力形式も Line delimited JSON になります。

## サーバとしての利用

コマンドラインツールの実体は `bin/server.js` です。
以下の手順で任意のポートでサーバを起動します。

```
$ npm install imi-enrichment-hojin-1.0.0.tgz
$ cd node_modules/imi-enrichment-hojin
$ node bin/server.js 3030
imi-enrichment-hojin-server is running on port 3030
```

なお、ポート番号を指定しなかった場合には以下のように使用方法が出力されて終了します。

```
$ node bin/server.js
Usage: node server.js [port number]
$
```

サーバが起動している状態で、 POST メソッドで JSON-LD を送信すると変換結果が出力されます。

```
$ curl -X POST -d '{"@context": "https://imi.go.jp/ns/core/context.jsonld","@type": "法人型","表記": "株式会社ほげほげ"}' localhost:3030
{
  "@context": [
    "https://imi.go.jp/ns/core/context.jsonld",
    "http://hojin-info.go.jp/ns/domain/biz/1/context.jsonld"
  ],
  "@type": "法人型",
  "表記": "株式会社ほげほげ",
  "組織種別位置": "前",
  "組織種別": {
    "@type": "コード型",
    "識別値": "301",
    "表記": "株式会社"
  },
  "メタデータ": {
    "@type": "hj:更新履歴型",
    "hj:更新者": {
      "@type": "実体型",
      "表記": "IMI法人種別抽出コンポーネント"
    },
    "種別": "INFO",
    "説明": "プロパティ(組織種別|組織種別位置) が追加されました。",
    "日時": {
      "@type": "日時型",
      "標準型日時": "2019-02-08T20:10:40.096+09:00"
    }
  }
}
$
```

# 開発者向け情報

## 環境構築

ソースアーカイブ `imi-enrichment-hojin-1.0.0.src.tgz` を入手して、
以下の手順でインストールします。

```
$ mkdir imi-enrichment-hojin
$ cd imi-enrichment-hojin
$ tar xvzf imi-enrichment-hojin-1.0.0.src.tgz
$ npm install
```

## テスト

以下の手順でテストが実行され、テスト結果が出力されます。

```
$ npm test

> mocha test/test.js



  imi-enrichment-hojin
    基本動作
      正常系
        ✓ ルートにある法人インスタンスに対する変換
        ✓ ルートにない法人インスタンスに対する変換
        ✓ @graph による複数インスタンスに対する変換
        ✓ hj:法人型 に対する変換
      異常系
        ✓ 法人型が見つからない場合は警告
        ✓ 複数の法人が列挙されている場合は警告
        ✓ 法人種別を判定するヒントがなく判定できなかった場合は警告
    各種の法人表記に対する対応
      ✓ 前株
      ✓ 後株
      ✓ 中間
      ✓ 公益財団法人・財団法人


  11 passing (15ms)

$
```


## ベンチマーク

以下の手順で大規模データ(法人インフォダウンロードデータから抽出した法人表記文字列19万件)が変換され、
結果が標準出力およびファイルに記録されます。

```
$ npm run stat

> imi-enrichment-hojin@1.0.0 stat imi-enrichment-hojin
> mocha test/stat.js



  imi-enrichment-hojin
    stat
      全体
        ✓ 入力件数: 196551 (100.00%)
        ✓ 実行時間: 3400 [msec]
        ✓ 10,000件あたり: 172.98 [msec]
      付与されたプロパティ
        ✓ 組織種別: 190198 (96.77%)
        ✓ 組織種別位置: 187749 (95.52%)
      分類
        ✓ 301:株式会社(前): 76573 (38.96%)
        ✓ 301:株式会社(後): 52863 (26.90%)
        ✓ 301:株式会社: 1916 (0.97%)
        ✓ 302:有限会社(前): 18004 (9.16%)
        ✓ 302:有限会社(後): 1639 (0.83%)
        ✓ 302:有限会社: 33 (0.02%)
        ✓ 303:合名会社(前): 70 (0.04%)
        ✓ 303:合名会社(後): 27 (0.01%)
        ✓ 305:合同会社(前): 759 (0.39%)
        ✓ 305:合同会社(後): 476 (0.24%)
        ✓ 305:合同会社: 23 (0.01%)
        ✓ 304:合資会社(前): 309 (0.16%)
        ✓ 304:合資会社(後): 58 (0.03%)
        ✓ 304:合資会社: 2 (0.00%)
        ✓ 399:その他の設立登記法人(前): 29977 (15.25%)
        ✓ 399:その他の設立登記法人(後): 6994 (3.56%)
        ✓ 399:その他の設立登記法人: 475 (0.24%)
        ✓ 判定不能: 6353 (3.23%)
      正誤判定
        ✓ 正解: 188434 (95.87%)
        ✓ 誤判定: 1119 (0.57%)
        ✓ 種別なし(複数法人): 397 (0.20%)
        ✓ 種別なし(自治体・国の機関等): 4544 (2.31%)
        ✓ 種別なし: 1316 (0.67%)
        ✓ 存在しない法人番号: 741 (0.38%)


  29 passing (23ms)

$

```

入力データの本体は `test/hojin.txt` です。
出力先のファイルは `test/output.csv` です。

`test/output.csv` は以下のようなレイアウトの CSV です。

```
法人番号,表記,組織種別,組織種別位置,種別,説明,法人番号公表サイトにおける組織種別
1010001054927,株式会社廣瀬商会　大阪支店特販事業部,301,前,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
1010001054943,株式会社樋口本店,301,前,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
1010001054984,株式会社ピー・アール現代,301,前,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
1010001055066,ヒゲタ醤油株式会社,301,後,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
1010001055157,株式会社ビッグアビリティ,301,前,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
1010001055388,富士エンタープライズ株式会社,301,後,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
1010001055454,富士石油販売株式会社,301,後,INFO,プロパティ(組織種別|組織種別位置) が追加されました。,301
```

BOM つき UTF-8 でエンコードされており、Excel で開くことで、実際にどのような変換が行われたのかを目視確認することができます。

また、この CSV では比較のために、「法人番号」列の値をもとに実際に法人番号公表サイトで設定されている組織種別を参考値として
「法人番号公表サイトにおける組織種別」として付与しています。

- 有限会社が株式会社に変更されたなどの理由で、法人表記から抽出された「組織種別」と「法人番号公表サイトにおける組織種別」が一致しないことがあります
- 「法人番号」列に無効であったり誤った法人番号が指定されている場合、「法人番号公表サイトにおける組織種別」は「該当法人番号なし」となります


## ファイル構成

開発対象となる Javascript は以下の３つです。

```
main.js : 関数本体
```

## メンテナンス

main.js の冒頭部分に以下のような `codes` オブジェクトが定義されています。
これは種別コードをキー、ic:コード型 のインスタンスを値として保持するオブジェクトです。
これらのオブジェクトをひな型として、出力に対して ic:組織種別 が付与されます。
コードリストの保持、指定に関してはいまだ明確なガイドラインがないために、
本コンポーネントではコードリストに関する情報を付与していません。

今後のコードリスト情報の確定・追加・変更の場合にあたっては ic:コード種別 を追加することで対応が可能です。

```
const codes = {
  "301": {
    "@type": "コード型",
    "識別値": "301",
    "表記": "株式会社"
  },
  "302": {
    "@type": "コード型",
    "識別値": "302",
    "表記": "有限会社"
  },
  "303": {
    "@type": "コード型",
    "識別値": "303",
    "表記": "合名会社"
  },
  "304": {
    "@type": "コード型",
    "識別値": "304",
    "表記": "合資会社"
  },
  "305": {
    "@type": "コード型",
    "識別値": "305",
    "表記": "合同会社"
  },
  "399": {
    "@type": "コード型",
    "識別値": "399",
    "表記": "その他の設立登記法人"
  }
};
```

法人名の表記に対して、法人種別を判定するためのフレーズは、
main.js 冒頭の `names` オブジェクトに定義されています。

```
const names = {
  "301": ["株式会社", "株式會社", "(株)", "（株）", "㈱"],
  "302": ["有限会社", "有限會社", "(有)", "㈲", "（有）"],
  "303": ["合名会社", "合名會社"],
  "304": ["合資会社", "合資會社", "（資）"],
  "305": ["合同会社", "合同會社", "（同）"],
  "399": [
    "一般財団法人",
    "一般社団法人",
    "社団法人",
    "医療法人",
  ]
};

```

たとえば「カブシキガイシャ〇〇」という社名に対して、「301:株式会社」である、と判定させたい場合には、
以下のようにフレーズを追加することで対応が可能です。

```
const names = {
  "301": ["株式会社", "株式會社", "(株)", "（株）", "㈱","カブシキガイシャ"],
  ...
}
```


# 制限事項

本コンポーネントは国税庁法人番号公表サイトで用いられている法人種別を対象としています。
定義は <https://www.houjin-bangou.nta.go.jp/documents/k-resource-dl-ver3.pdf> の4ページ、
項番15の法人種別です。


本コンポーネントでは法人表記をもとに、以下の法人種別のいずれかであるかを判定します。

- 301 株式会社
- 302 有限会社
- 303 合名会社
- 304 合資会社
- 305 合同会社
- 399 その他の設立登記法人

ただし、以下の法人種別は表記からは容易に判定できないので、本コンポーネントではこれらの法人種別は使用されません。

- 101 国の機関
- 201 地方公共団体
- 401 外国会社等
- 499 その他
