English
JapaneseAddress draft value type subclass
A Japanese postal address as the value of an address Property. schema.org PostalAddress terms where the meaning matches, plus the Japanese structure (machiaza, chome, banchi, go), JIS and local-government codes, the Address Base Registry town id and the residential-indication flag. Every field is optional; addressText alone is acceptable when the address cannot be structured.
| Kind | value type: used inside an attribute, not as an entity of its own |
| Subclass of | A subclass of https://schema.org/PostalAddress, a type outside this catalog: this type is narrower or adds fields. Fields whose meaning matches use the parent vocabulary's IRIs. The vocabulary states the relation as rdfs:subClassOf. |
| IRI | https://datamodels.jp/ns/common/JapaneseAddress |
| @context | https://datamodels.jp/context/common/v1.jsonld |
| JSON Schema | /schema/common/JapaneseAddress/v1.json |
| Licence | CC0 1.0: the files (@context, JSON Schema, examples) can be used without conditions |
These @context and JSON Schema URLs (version aliases) always point to the latest compatible version.
For URLs that never change, see Versions. More in URLs and versions.
Types and relationships
used as a value typeother subjectN more links: continued on that type's page
Fields
| Field | Description | Value |
|---|---|---|
addressCountry | Country. Always JPhttps://schema.org/addressCountry | string = JP |
postalCode | Postal code, 7 digits with or without hyphenhttps://schema.org/postalCode | string, pattern ^\d{3}-?\d{4}$ |
addressRegion | Prefecture namehttps://schema.org/addressRegion | string |
addressLocality | Municipality name. For designated cities includes the ward (e.g. 横浜市中区)https://schema.org/addressLocality | string |
machiaza | Town or district name (町字: 町名, 大字, 字), without chomehttps://datamodels.jp/ns/common/machiaza | string |
chome | Chome (丁目), digits only ("一丁目" → "1")https://datamodels.jp/ns/common/chome | string, pattern ^\d+$ |
banchi | Banchi (番地): in a residential-indication area the block number (街区符号); elsewhere the whole lot number (地番), branch number included, for example 4638-1https://datamodels.jp/ns/common/banchi | string |
go | Go (号): in a residential-indication area the residence number (住居番号). Empty for a lot number (地番): its branch number stays in banchihttps://datamodels.jp/ns/common/go | string |
buildingName | Building name, room number and anything below gohttps://datamodels.jp/ns/common/buildingName | string |
residentialIndication | true in a residential-indication area (banchi/go are block and residence numbers), false for lot numbers (地番)https://datamodels.jp/ns/common/residentialIndication | boolean |
jisPrefectureCode | Prefecture code (JIS X 0401, 2 digits)https://datamodels.jp/ns/common/jisPrefectureCode | string, pattern ^\d{2}$ |
jisMunicipalityCode | Municipality code (JIS X 0402, 5 digits including the prefecture code)https://datamodels.jp/ns/common/jisMunicipalityCode | string, pattern ^\d{5}$ |
localGovernmentCode | Local government code (全国地方公共団体コード: JIS X 0402 plus a check digit, 6 digits)https://datamodels.jp/ns/common/localGovernmentCode | string, pattern ^\d{6}$ |
abrMachiazaId | Address Base Registry town id (町字ID, 7 digits). Unique together with localGovernmentCodehttps://datamodels.jp/ns/common/abrMachiazaId | string, pattern ^\d{7}$ |
addressText | Full address as one normalised line. Also the fallback when structured fields are unavailablehttps://datamodels.jp/ns/common/addressText | string |
Using this model
Other models use this value type as the value of an attribute. Checking data that has such an attribute reads this schema too (Validate JSON).
Example
Most examples are a fictional scenario (heavy rain in Chiyoda, Tokyo). Place names and codes are real; the events, people and teams are invented. Some examples copy a real row of a published list instead; their notes name the source. See writing examples.
json
{
"addressCountry": "JP",
"postalCode": "102-8688",
"addressRegion": "東京都",
"addressLocality": "千代田区",
"machiaza": "九段南",
"chome": "1",
"banchi": "2",
"go": "1",
"buildingName": "千代田区役所",
"residentialIndication": true,
"jisPrefectureCode": "13",
"jisMunicipalityCode": "13101",
"localGovernmentCode": "131016",
"abrMachiazaId": "0008001",
"addressText": "東京都千代田区九段南1丁目2番1号"
}Files: example.json
Something missing or wrong?
Open an issue, or propose new attributes or models with the proposal form. How it works: Contributing. The source files (notes, mapping tables) are on GitHub.
Referenced standards
The standards this model corresponds to, field by field. Open one to see its table.
The Digital Agency's Address Base Registry (town, lot-number, and residential block and residence datasets)
Column names and meanings checked on 2026-10-30 in the registry's data format specification (データフォーマット(仕様確定版), 2024-01-15) published on the page above; the June 2025 version is still being prepared. The datasets used are 03 towns (mt_town), 04 lot numbers (mt_parcel), 05 residential blocks (mt_rsdtdsp_blk) and 06 residences (mt_rsdtdsp_rsdt). The Digital Agency's abr-geocoder uses mostly the same names in its results, except that the chome is only the written form (chome, no chome_number) and lg_code and machiaza_id are under ids, not structured_address. This table explains the correspondence; it is not a conversion for datamodels convert.
| This model | Maps to | Note |
|---|---|---|
addressCountry | no counterpart | not in the data; always JP |
postalCode | post_code | a column of the town dataset (mt_town). When it holds several codes (separated by semicolons), use one only when other information decides which; otherwise leave postalCode out |
addressRegion | pref | |
addressLocality | county + city + ward | county, municipality and designated-city ward joined |
machiaza | oaza_cho + koaza | oaza/town and koaza joined; the chome goes to the JapaneseAddress field chome |
chome | chome_number | chome_number is the chome as digits; the registry's chome column is the written form, such as 一丁目 |
banchi | blk_num、prc_num1 + prc_num2 + prc_num3 | The block number (blk_num) in a residential-indication area. For a lot number, the main number (prc_num1), its sub-number (prc_num2) and the sub-number's sub-number (prc_num3), joined with hyphens and empty parts left out (for example 4638-1); joining with hyphens is this catalog's convention. The registry notes that these can exceptionally contain more than digits. |
go | rsdt_num + rsdt_num2 | The residence number (rsdt_num). When a residence number is made of two numbers (the special rule for housing complexes and high-rise buildings, or a branch number), the second one (rsdt_num2) is joined with a hyphen (this catalog's convention). Empty for a lot number. |
residentialIndication | rsdt_addr_flg | 1 (residential indication in force) → true, 0 (not in force) → false. The flag is per town: a town with both kinds of area has two records, and the value of the record the address belongs to is used. |
localGovernmentCode | lg_code | |
jisPrefectureCode | no counterpart | the first two digits of lg_code |
jisMunicipalityCode | no counterpart | the first five digits of lg_code |
abrMachiazaId | machiaza_id | |
buildingName | no counterpart | not in the registry |
addressText | no counterpart | not in the registry; made by joining the fields |
Mapping file (YAML) for converting data from this standard: abr.yaml (see Mapping files)
Licence of this standard: Public Data License (version 1.0) (PDL1.0). The lot-number data (地番マスター) is also subject to the terms of use of the registry office map data (登記所備付地図データ利用規約); see the terms of use for the data linked from the page above.
Digital Agency GIF core data model "Address"
GIF keeps chome inside streetAddress (町字) and folds everything below into a single cityBlock. JapaneseAddress keeps chome, banchi and go apart, so a conversion to GIF concatenates them.
| This model | Maps to | Note |
|---|---|---|
addressCountry | country | GIF uses a country code list; JP corresponds |
postalCode | postalCode | |
addressRegion | prefecture | |
addressLocality | cityAndCounty | both include county and designated-city ward names |
machiaza | streetAddress | GIF streetAddress includes chome; corresponds to machiaza + chome |
chome | streetAddress | included in streetAddress, see above |
banchi | cityBlock | GIF folds everything below the town into one field; corresponds to banchi + go |
go | cityBlock | |
buildingName | buildingNameEtc | |
addressText | fullAddress | |
localGovernmentCode | localGovernmentCode | |
abrMachiazaId | streetAddressId | both are the Address Base Registry town id |
jisPrefectureCode | no counterpart | not in GIF; derivable from the first two digits of localGovernmentCode |
jisMunicipalityCode | no counterpart | not in GIF; the first five digits of localGovernmentCode |
residentialIndication | no counterpart | not in GIF |
Mapping file (YAML) for this standard: gif-address.yaml (see Mapping files)
Licence of this standard: CC BY 4.0 (schema), CC0 1.0 (repository)
The address column of GSI's designated emergency evacuation site and designated shelter data
The address is one line only; there are no structured columns.
| This model | Maps to | Note |
|---|---|---|
addressCountry | no counterpart | not in the data; always JP |
addressText | 住所 | |
localGovernmentCode | no counterpart | not in the data; derivable from the municipality code in the file name |
Mapping file (YAML) for converting data from this standard: gsi-address.yaml (see Mapping files)
Licence of this standard: GSI's terms of use for its content (国土地理院コンテンツ利用規約) and the site's notes on use (ご利用上の注意)
Municipal standard open dataset, data item definition sheet A (2026-08-01), location columns (Digital Agency)
Of definition sheet A, 12 datasets share the same location columns: 01 public facilities, 02 cultural properties, 03 designated emergency evacuation sites, 05 childcare facilities, 07 public Wi-Fi, 08 AEDs, 09 care service providers, 10 medical institutions, 11 tourist facilities, 12 events, 13 public toilets, 14 fire water supplies (15 food business permits has only the full address, the location's local government code and the town id). Columns are given as the Japanese name (English item name); item numbers differ per dataset.
| This model | Maps to | Note |
|---|---|---|
addressCountry | no counterpart | not in the datasets; always JP |
postalCode | 郵便番号 (contactPointPostalCode) | by definition the contact point's postal code, which may differ from the location's, so the converter does not put it into postalCode; not in 12 events, 13 public toilets, 14 fire water supplies |
addressRegion | 所在地_都道府県 (prefecture) | |
addressLocality | 所在地_市区町村 (city) | both include county and designated-city ward names |
machiaza | 所在地_町字 (streetAddress) | the dataset's town includes chome (e.g. 青葉町一丁目); corresponds to machiaza + chome |
chome | 所在地_町字 (streetAddress) | included in the town, see above; convert kanji numerals (一丁目 → 1) |
banchi | 所在地_番地以下 (cityBlock) | everything below the town in one column (e.g. ○-○); corresponds to banchi + go |
go | 所在地_番地以下 (cityBlock) | |
buildingName | 建物名等(方書) (buildingNameEtc) | |
addressText | 所在地_連結表記 (fullAddress) | prefecture through building name as one line. Required in the datasets, so it is there even when the structured columns are empty |
localGovernmentCode | 所在地_全国地方公共団体コード (locatedLocalGovernmentCode) | the first column, 全国地方公共団体コード (localGovernmentCode), is the publishing government's code and differs when the location lies outside its area; use the location's code for the address |
abrMachiazaId | 町字ID (streetAddressId) | both are the Address Base Registry town id. The dataset's example writes it with a hyphen (0008-001); remove it for the 7 digits |
jisPrefectureCode | no counterpart | not in the datasets; the first two digits of localGovernmentCode |
jisMunicipalityCode | no counterpart | not in the datasets; the first five digits of localGovernmentCode |
residentialIndication | no counterpart | not in the datasets |
Mapping file (YAML) for converting data from this standard: jichitai-opendata-address.yaml (see Mapping files)
Licence of this standard: Public Data License (Version 1.0) (PDL1.0), compatible with CC BY 4.0
Notes
- A value type, not an entity type. Use it as the value of an
addressProperty (IRI https://schema.org/address) and reference the schema with $ref from an entity schema. - The official Japanese address model is the Digital Agency's GIF core data model 住所 (Address). JapaneseAddress covers the same information; the field-by-field correspondence is in mapping/gif-address.yaml and on the page. GIF is published as XSD and Excel, not as JSON-LD or JSON Schema, which is why this value type exists.
- Upstream considered: the type is minted as a catalog value type and declared a subclass of schema.org PostalAddress (2026-10-12), because it adds the Japanese address parts (machiaza, chome, banchi, go) and the codes. schema.org PostalAddress terms are reused where the meaning matches (addressCountry, postalCode, addressRegion, addressLocality). streetAddress is not used: schema.org means the street line of a Western address by it, while GIF uses the same name for 町字. Reusing the IRI would carry an ambiguous meaning; the structured fields and addressText replace it, and the GIF mapping records the correspondence.
- Codes follow JIS X 0401 (prefecture, 2 digits), JIS X 0402 (municipality, 5 digits) and the 全国地方公共団体コード (6 digits with check digit). abrMachiazaId is the 町字ID of the Digital Agency's Address Base Registry.
- GeoProperty coordinates are WGS84 by the GeoJSON specification; JGD2011 coordinates can be used as-is at the precision relevant here.
- Decided on 2026-10-03: in a lot-number (地番) area, banchi holds the whole lot number, branch number included (for example 4638-1), and go stays empty, because a branch number is not a 号. The Address Base Registry keeps residential-indication block and residence numbers (rsdt) apart from lot numbers (chiban); this came up when trying real data for the converter (geolonia/datamodels-toolkit#3).
- How far the address is split follows the Digital Agency's Address Base Registry (2026-10-30). Joining split fields later takes a simple rule; splitting a joined field again means parsing text, which can go wrong. GIF folds everything below the town (block and residence numbers, or the lot number) into one cityBlock; JapaneseAddress keeps chome, banchi and go apart and joins them for a conversion to GIF: machiaza and chome become streetAddress, banchi and go become cityBlock (mapping/gif-address.yaml). The registry's finer parts (koaza, the second part of a residence number, the sub-numbers of a lot number) are not separate fields: they go into machiaza, go and banchi, and anything finer can be looked up in the registry: the town is identified by abrMachiazaId together with localGovernmentCode, and a block, residence or lot by banchi and go on top of that. The correspondence with the registry is in mapping/abr.yaml.
- Decided on 2026-10-30 to keep the field names rather than take the registry's column names (blk_num, rsdt_num, prc_num1 to 3 and so on). The registry's columns belong to separate datasets (lot numbers, blocks, residences), with block numbers and lot numbers in different datasets; in a model, one banchi for either is easier to use.