Skip to content

Latest commit

 

History

History
703 lines (431 loc) · 36.3 KB

Example-20240701.md

File metadata and controls

703 lines (431 loc) · 36.3 KB

Updated 7-12-2024

Definition of Format

This section follows the use of case sensitivity described in RFC 8174:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [^RFC2119] [^RFC8174] when, and only when, they appear in all capitals, as shown here

File Type

There are a variety of potential file types that could be used, such as CSV, XML, JSON, and others. Of all of the options, it appears that a Comma Separated Value (CSV) 1 file is the most uniformly understood and easiest to use. For one, most relevant individuals know how to use a CSV file or have access to software that will automatically figure out how to open a CSV file. One downside may be that while a CSV file is universally known - it's difficult to extend a CSV file, since calculations are often built on fixed column - not by looking up the column header name or description. That can be mitigated to some extent by building in as many optional fields as we can conceive of in the first version, and by creating an accompanying data dictionary file that explains and defines each field, but is certainly a downside to using a CSV.

On the other hand, JavaScript Object Notation (JSON) is also well-known in the research and technical communities and can be human-readable rather than just values separated by commas. There is also software that can convert a JSON file to a CSV file 2, and it is easily extensible.

Based on the widespread use of CSV files, it seems this is the primary file that should be made available. ISPs can of course optionally consider generating a JSON file or other file types.

File Format

The CSV file uses the "text/csv" media (MIME) type 3, which is defined in the IANA registry of MIME types 4.

The character encoding of the CSV file MUST be UTF-8.

When served over HTTP, the most common use case, the media type used in the Content-Type header MUST have the parameter of "charset=utf-8".

Format Guidelines Conform to RFC 4180

The format of the published CSV MUST adhere to RFC 4180 1.

That RFC defines several key formatting requirements, especially in Section 2, which requires close reading my operators. This covers a variety of requirements, such as that the format MUST use CRLF for line breaks (a.k.a. "Carriage Return, Line Feed" - CRLF), that you MAY use spaces within a field value, MAY use commas within a field value, and MAY use line returns within a field value. Please read RFC 4180 carefully to ensure format compliance.

This RFC 4180 format can be imported into recent versions of Microsoft Excel and LibreOffice, as well as other software clients.

The schema also follows the proposed standard guidelines in the U.K. National Archives CSV Schema Language version 1.2 5.

File Header Required

The CSV file MUST contain a header row. In addition, when served over HTTP (the most common case), the media-type used in the Content-Type HTTP header MUST have the parameter of "header=present".

While a file header is not strictly required for CSV files as defined in RFC 4180, it is required here because it provides a firm definition of field names without having to consult a separate file for this information.

The file header will appear on the first line of the file and will include each field name, separated by commas and ending with a line break (i.e., field_name,field_name,field_name CRLF).

Schema Version 1

This is the first version of the schema, version 1. Subsequent versions will increase one integer at a time, from 1 to 2, and so on. The schema version MUST be listed in the media type of the file.

For example, "text/csv;header=present;charset=utf-8;schema-version=bblabel-1", with the "bblabel-1" part representing the first version of the broadband label schema. The second, when/if defined, would be "bblabel-2", then "bblabel-3" for the third, and so on.

Note: This document attempts to define a number of both required and optional fields. This is being done in a way to try to think to future needs and a variety of uses, because adding fields means adding columns to the definition of the CSV schema, and thus the definition of a new schema version.

One Row is One Broadband Label

Each row represents a distinct broadband label and is delimited in the CSV file with a line break.

Format of File Name

Underscore characters and spaces MUST NOT be used in the file name.

The file name MUST follow this standard format in the order below.

  1. Date when published, in the ISO 8601 format 6, with hyphens. Thus the format is YYYY-MM-DD, so 2025-01-15 for example to represent January 15, 2025.

  1. Regulator Unique Provide Identifier. This will vary by jurisdiction. In the United States for example, it will be the FCC Registration Number (FRN) 7.

  2. Country Code, using the International Organization for Standardization (ISO) ISO 3166-3 format. This the "Alpha-3" code – a three-letter code that represents a country name, which is usually more closely related to the country name than the two-letter code. For example, the United States of America is USA and Canada is CAN. 8

  1. The provider MAY optionally include additional information in the field name (see the use of "ABCD" below). For example, the file might include "mobile" or "5g-fwa" in the name.

Examples (non-exclusive): 2025-01-15-0003768165-USA.csv, 2025-01-15-0005937974-USA-ABCD.csv, 2025-01-15-0005937974-USA-mobile.csv

File Contents

The file MUST contain the required fields. There are several optional fields which MAY also be included by providers. All these fields are all detailed below. If additional fields are defined in the future, the schema will need to be updated.

If any field does not apply, whether required or optional, then it MUST be left empty (null).

All examples are non-exclusive.

Required Fields

  1. Date Published

Date when published, in the ISO 8601 format 6, with hyphens. Thus the format is YYYY-MM-DD, so 2025-01-15 for example to represent January 15, 2025.

Name: date_published

Type/Format: date

Examples: 2025-01-15, 2025-11-02, 2025-06-06

  1. Regulator Name

Initially this will only be the FCC, but as it is possible that other regulators may wish to use this format, a regulator field is included. This field MUST be in the file and MAY be used. If this field is empty, users of the file SHOULD assume the regulator is the FCC.

Name: regulator_name

Type/Format: string

Examples: FCC, OFCOM, ECOI, MIC

  1. Regulator Version Number

If requirements ever change, as we expect they will, having a required version field will be very useful. Given that labels must be maintained historically, it will be useful to know that a particular historical or current label is compatible with a specific regulatory requirement version. This field will begin from 01 for the first version, with the next being 02, all the way up to 99. This field MUST be in the file and MAY be populated. If this field is not used or is not applicable it SHOULD be left empty.

If and when a regulator changes the requirements for these labels, a new version of the schema will also need to be published.

Field: regulator_version_number

Type/Format: numeric, range(01, 99)

Examples: 01, 02, 55, 77

  1. Access Network Connection Type A provider may need to update a specific label due to error, new data, or other reason. In this case a version number should be incremented, with the default first version being 1.

This field MUST be in the file and MUST be populated.

Field: connection_type

Type/Format: string

Examples: fixed, mobile, satellite

  1. FCC Registration Number (FRN). This is a 10-digit unique identifying number that is assigned to organizations doing business with the Commission. An organization can be issued a FRN through the FCC's Commission Registration System (CORES) or by filing FCC Form 160 7. The FRN is a required part of the label identification number (but if providers outside of the US use this schema, this field can be left empty). This field MUST be in the file and MUST be populated by providers in the US. For providers outside of the US, it MAY be left empty.

Name: fcc_registration_number

Type/Format: numeric, range(0000000000, 9999999999)

Examples: 0005937974, 0003768165, 0005937974

  1. Unique Plan Identifier (UPI). This is a combination of plan type (F or M), plus the FRN from above (up to 10 numbers), plus an additional unique string of up to 15 characters.

The unique alphanumeric string part at the end of the UPI MUST only contain capital letters (A-Z) and numbers (0-9). It MUST NOT include any special characters or other delimiters such as hyphens. This part of the string is chosen by the provider. This field MUST be in the file and MUST be populated by providers in the US. For providers outside of the US, it MAY be left empty.

Name: unique_plan_identifier

Type/Format: string, limited to a maximum of 26 characters, no special characters, no delimiters, all letters capitalized.

Examples: F0005937974TIER1, F0005937974ABCD12341234, F0005937974ABCDEFGHIJ12345

  1. Network Technology Type. This defines the access network technology used for a given BIAS offering. This is a numeric field using FCC-defined technology codes, limited to no more than 3 digits length. (In the future, it may be better to register these codes with IANA and to maintain them globally, rather than on a regulator-specific basis.)

  • If a Fixed plan type, refer to the FCC's Fixed Technology Codes 9. For example, hybrid-fiber coaxial (HFC) is "40" and fiber to the premises (FTTP) is "50".

  • If a Mobile plan type, refer to the FCC's Mobile Technology Codes 10. For example, 3G is "300" and 5G is "500". This field MUST be in the file and MUST be populated.

Name: network_technology_type

Type/Format: numeric, range (0, 999)

Examples: 40, 50, 500

  1. Provider Name. Name of the BIAS provider delivering a specific service.

This field MUST be in the file and MUST be populated. Name: provider_name

Type/Format: string, limited to 100 characters

Examples: Xfinity Internet, Comcast Business Class, T-Mobile, Google Fiber

  1. Service Plan Name. Name of the provider's specific tier of service offered for sale. If a provider has only one service offering, it is possible this field will be empty. This field MUST be in the file and MAY be populated. Name: service_plan_name

Type/Format: string, limited to 100 characters

Examples: Extreme 500, Fiber 2G, Turbo 5G Plus

  1. Download Bandwidth Units. The applicable bits per second of bandwidth. This field MUST be in the file and MUST be populated.

Name: bandwidth_download_units

Type/Format: string, length(4)

Examples: kbps, Mbps, Gbps, Tbps, Pbps

  1. Download Bandwidth, Marketed, Low. What the customer is being or has been sold. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_download_marketed_low

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Download Bandwidth, Marketed, High. What the customer is being or has been sold. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_download_marketed_high

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Download Bandwidth, Typical, Low. What the customer typically can expect to receive. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_download_typical_low

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Download Bandwidth, Typical, High. What the customer typically can expect to receive. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_download_typical_high

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Upload Bandwidth Units. The applicable bits per second of bandwidth. This field MUST be in the file and MUST be populated.

Name: bandwidth_upload_units

Type/Format: string, length(4)

Examples: kbps, Mbps, Gbps, Tbps, Pbps

  1. Upload Bandwidth, Marketed, Low. What the customer is being or has been sold. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated. Name: bandwidth_upload_marketed_low

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Upload Bandwidth, Marketed, High. What the customer is being or has been sold. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_upload_marketed_high

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Upload Bandwidth, Typical, Low. What the customer typically can expect to receive. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_upload_typical_low

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Upload Bandwidth, Typical, High. What the customer typically can expect to receive. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If it is an absolute number, then it should generally be one to three digits, because after 999 then a new bandwidth unit is used. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: bandwidth_upload_typical_high

Type/Format: numeric, length(1-3)

Examples: 2, 75, 500

  1. Latency, Idle, Low. This is a number, in milliseconds, of the typical idle latency a user will experience. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: latency_idle_low

Type/Format: numeric, length(*,10)

Examples: 2, 75, 500

  1. Latency, Idle, High. This is a number, in milliseconds, of the typical idle latency a user will experience. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MUST be populated.

Name: latency_idle_high

Type/Format: numeric, length(*,10)

Examples: 2, 75, 500

  1. Currency. Since it is possible that this machine-readable label specification may be used outside of the US, and for the avoidance of ambiguity, a currency code MAY be used. If it is empty, users of the file MUST assume that the currency is US Dollars.

This is limited to three characters in length and uses the International Organization for Standardization (ISO) ISO 4217:2015 format. This format specifies the structure for a three-letter alphabetic code and an equivalent three-digit numeric code for the representation of currencies.

If this field is used, it MUST use the alphabetic codes in ISO 4217:2015, which are human-readable, as opposed to the numeric code. 11

Name: currency

Type/Format: string, max length 3 characters

Examples: USD, GBP, EUR

  1. Price Type. This describes whether a price is for pre-paid service, post-paid, per-line, and so on. In cases where the pricing is a combination of factors, the provider may choose to use the primary pricing type here and a qualifier in the next subsequent Price Type Details field, or may just choose Other here and define all details in Price Type Details. It is highly recommended that the string value for this field be limited to the following options:
  • Pre-Paid
  • Post-Paid
  • Volume-Based (example: per GB, per TB)
  • Per-Line
  • Per-Device (example: tablet, phone)
  • Per-Location (example: per home, per office location)
  • Per-Organization
  • Per-Person
  • Per-Time (example: per day, per month)
  • Other This field MUST be in the file and MUST be populated. The subsequent price_type field SHOULD in some cases be used in conjuction with this field. For example, if the value of this field was Volume-Based, then price_type might be Per TB.

Name: price_type

Type/Format: string

Examples: Pre-Paid, Post-Paid, Per-Line

  1. Price Details. This is a string intended to address instances where pricing is a combination or attributes, or something else we have not envisioned (given the dynamism of pricing mechanisms). In many cases this field may be empty. While this field MUST be used when price_type = 99 from above, it MAY also be used for other pricing types at the discretion of the provider. This field MUST be in the file and MAY be populated.

Name: price_details

Type/Format: string

Examples: Requires activation of one new device., Price covers first 1 GB of data transferred. Data transfer billed at $1 per GB thereafter., For new customers only.

  1. Recurring Price. This is how much a customer is charged on a recurring basis, if applicable, such as per month or per week, as defined above in price_type. This price MAY include two decimal places and is numeric.

7 digits plus two decimal places, fixed length (ex: price is $125/month, so value is 0000125) This field MUST be in the file and MUST be populated. Name: price_recurring

Type/Format: numeric, range(0000000.01-9999999.99)

Example: 29, 29.99, 399.00

  1. Introductory Fee. If this is populated, it indicates that there is an introductory rate. If introductory price does not apply, then this field MUST be empty. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_introductory Format/Type: Numeric Examples: 9, 9.99, 12.99

  2. Introductory Fee Details. This is used to list the details of any introductory fee that may apply to a given BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_introductory_description Format/Type: string Examples: Only available to new customers., Fee for first three months., Fee for first three devices.

  3. Contract Required. Defines whether the price requires a contract and is either Yes or No.

This field MUST be in the file and MUST be populated.

Name: contract_required

Type/Format: string, length(2,3)

Examples: Yes, No

  1. Contract Details. If a contract is required, the field provides more information about the particulars. If there is no contract required, it is expected that this field will be empty. This field MUST be in the file and MAY be used. If it does not apply, it SHOULD be left empty. Name: contract_details

Type/Format: string

Examples: Contract is 1 year., Valid for first 3 months., Contract must be digitally signed within 7 days of installation.

  1. Contract Terms Uniform Resource Indicator (URI). If a contract is required, then a URI MUST be provided in this field. If there is no contract required, it is expected that this field will be empty. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: contract_terms_uri

Type/Format: identifier, uri

Examples: https://example.com/contract-terms/internet/, https://example.com/internet-contract/, https://example.com/legal/terms/contracts.html

  1. One-Time Fee Amount. This is used to list the details of any one-time fees that may apply to a given BIAS offering. This price MAY include two decimal places and is numeric. 7 digits plus two decimal places, fixed length (ex: price is $125/month, so value is 0000125) This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_one_time_amount Type/Format: numeric, range(0000000.01-9999999.99)

Example: 29, 29.99, 399.00

  1. One-Time Fee Details. This is used to list the details of any one-time fees that may apply to a given BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_one_time_details

Format/Type: string

Examples: Professional installation fee of $100 required., Shipping fee of $20 for sending equipment., $10 device provisioning fee.

  1. Recurring Fees. If this is populated, it indicates that there are recurring fees, such as for the rental of a device. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_recurring Type/Format: string Examples: 9, 9.99, 12.99; 1.99

  2. Recurring Fee Details. This is used to list the details of any recurring fees that may apply to a given BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_recurring_description Format/Type: string Examples: Monthly device rental., Cloud storage fee., Streaming video package; Sports package.

  3. Pass Through Fees (Maximum). If this is populated, it indicates that there are recurring pass through fees, such as a fee required by a particular city or county. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_pass_through_recurring Type/Format: string Examples: 9, 9.99, 12.99

  4. Early Termination Fee. Defines whether there is a fee charged for early termination. If there is NOT a fee, then the value in this field should be zero (0). This fee MAY include two decimal places and is numeric. This field MUST be in the file and MUST be populated. If it does not apply, it MUST contain the value 0. Name: fee_early_termination

Type/Format: string

Examples: 9.99, 100, Varies

  1. Early Termination Fee Details. This is used to list the details of any early termination fees that may apply to a given BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_early_termination_description Format/Type: string Examples: $100 charged if service is terminated before the end of one year., $25, $10 for every month remaining in contract term.

  2. Government Taxes. The field indicates whether any government taxes and fees are included in the price of a given BIAS offering. This may include those taxes and fees charged by franchise authorities, cities, states, the federal government, or other governmental or government-related entities. This field MUST be in the file and MUST be populated. It is recommended that the value be one of these: Included, Varies, Not Applicable. Name: government_taxes Format/Type: string Examples: Included, Varies, Not Applicable

  3. Data Usage Policy Applies. Defines whether a given BIAS offering has a data usage policy and is either Yes or No. This field MUST be in the file and MUST be populated.

Name: policy_data_usage

Type/Format: string, length(2,3)

Examples: Yes, No

  1. Data Usage Fee. Defines whether there is a fee charged for extra data usage. If there is NOT a fee, then the value in this field should empty. This fee MAY include two decimal places and is numeric. This field MUST be in the file and MUST be populated. If it does not apply, it MAY be left empty. Name: fee_data_usage

Type/Format: string

Examples: 1, 10, Varies

  1. Data Usage Fee Details. This is used to list the details of any data usage fees that may apply to a given BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty. Name: fee_data_usage_description Format/Type: string Examples: $1 per GB after the first 1 TB., No fee but bitrates are reduced to 100 Mbps after 10 GB of usage., $2 per GB during peak times and $1 per GB during off-peak times.

  2. Data Usage Policy Uniform Resource Indicator (URI). This is the URI for a data usage policy that may apply to a specific BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: uri_data_usage

Type/Format: identifier, uri

Examples: https://example.com/data-usage/internet/, https://example.com/datausagepolicies, https://example.com/data-usage.html

  1. Restrictions Apply, 1 number - either 0 for YES or 1 for NO] ex: 0 This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: restrictions_apply Type/Format: string Examples: Site survey required, Qualified for a low-income offering, Mobile service only available to existing customers of wireline service

  1. Network Management Policy Uniform Resource Indicator (URI). This is the URI for a network management policy that may apply to a specific BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: uri_policy_network_management

Type/Format: identifier, uri

Examples: https://example.com/network-management/internet/, https://example.com/networkpolicies, https://example.com/network-management.html

  1. Privacy Policy Uniform Resource Indicator (URI). This is the URI for a privacy policy that may apply to a specific BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: uri_policy_privacy

Type/Format: identifier, uri

Examples: https://example.com/privacy/internet/, https://example.com/privacy-policies/, https://example.com/privacypolicy.html

  1. Customer Support Information Uniform Resource Indicator (URI). This is the URI containing information about how to obtain customer support for a specific BIAS offering. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: uri_customer_support

Type/Format: identifier, uri

Examples: https://example.com/support/internet/, https://example.com/support, https://example.com/support.html

  1. Customer Support Phone Number. This is the telephone number a customer can use to contact customer support. The field MUST use the International Telecommunications Union (ITU), Telecommunication Standardization Sector (ITU-T) E.164-format telephone number. 12 It MUST contain only numbers; no parenthesis marks, hyphens, periods, or other delimiting marks are permissible. For example, while a North American number may be represented variously as +1-800-555-1212, 1-800-555-1212, 800-555-1212, (800) 555-1212, 800.555.1212, or other format, this field MUST NOT contain non-numeric characters. If no customer support phone number is provided, this field MAY be left empty. This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.

Name: customer_support_phone

Type: numeric, length(*,15)

Examples: 18005551212, 18885551212, 12675551212

Additional Fields for Optional Use

  1. Country Code: Since it is possible that this machine-readable label file specification may be useful outside of the US, an optional country code is included. This MUST be limited to three characters in fixed length. It MUST use the International Organization for Standardization (ISO) ISO 3166-3 format. This the "Alpha-3" code – a three-letter code that represents a country name, which is usually more closely related to the country name than the two-letter code. For example, the United States of America is USA and Canada is CAN. 8

This field MUST be in the file and MAY be populated.

Name: country_code

Format/Type: string, length(3)

Examples: USA, CAN, JPN

  1. Autonomous System Number (ASN). It may be useful to include a provider's ASN in the file. One example of this may be that a researcher is collecting network measurements using source IP address, which can be used to identify the ASN, or ASN is part of the collected data (such as related to the Border Gateway Protocol, BGP, for routing security to see if a Route Object Authorization, ROA, was issued), making it easy for a researcher to find labels based on the ASN or to combine label files with their data.

A complicating factor can be that some ISPs have several ASNs, though often these aggregate up into one primary ASN. In other cases, small ISPs may not have their own ASN and thus may be using the ASN of their upstream provider. For these reasons, this field is considered optional.

ASN as maintained by the Internet Assigned Numbers Authority (IANA). 13 In North America, these are issued by the American Registry for Internet Numbers (ARIN). 14 For US ISPs, the ARIN ASN list shall be used. 15 Until 2007, ASN were defined as 16-bit integers, which allowed for a maximum of 65,536 assignments. But the IANA is now assigning 32-bit ASNs up to 4,294,967,295. As a result this field will be numeric and limited to 10 digits in length. This field MUST be in the file and MAY be populated.

Name: asn

Format/Type: string, length(0,4294967295)

Examples: 7922, 14593, 701

  1. Additional Terms Uniform Resource Indicator (URI). This is the URI for any additional terms and/or policies that may apply to a specific BIAS offering. If nothing applies, this field should be left empty. If multiple policies apply, then URIs MUST be separated by a semi-colon.

This field MUST be in the file and MAY be populated.

Name: uri_policy_additional_terms

Type/Format: identifier, uri

Examples: https://www.example.com/terms-of-service/, https://www.example.com/terms/;https://www.example.com/abuse/, https://www.example.com/anti-abuse/

  1. Language. This field can optionally specify the language used in the machine-readable file. The default language shall be English. This field will use the ISO 639-3 format 16, which is a three letter format This field MUST be in the file and MAY be populated. If it does not apply, it SHOULD be left empty.
  1. Latency, Working, Low. This is a number, in milliseconds. It latency under normal working conditions, otherwise known as latency under load. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MAY be populated.

Name: latency_working_low

Type/Format: numeric, length(*,10)

Examples: 2, 75, 500

  1. Latency, Working, High. This is a number, in milliseconds. It latency under normal working conditions, otherwise known as latency under load. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MAY be populated.

Name: latency_working_high

Type/Format: numeric, length(*,10)

Examples: 2, 75, 500

  1. Jitter, Low. This is a number, in milliseconds. It is the variability of working latency. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MAY be populated.

Name: jitter_low

Type/Format: numeric, length(*,10)

Examples: 2, 75, 500

  1. Jitter, High. This is a number, in milliseconds. It is the variability of working latency. Depending on the type of service offered, this MAY be an absolute number or MAY be a range. If there is only one number, then the value for the respective "low" and "high" fields MUST be the same. When a range is appropriate, then the "low" and "high" numbers will differ. This field MUST be in the file and MAY be populated.

Name: jitter_high

Type/Format: numeric, length(*,10)

Examples: 2, 75, 500

  1. Uptime. Also known as availability, and expressed as a percentage, with a maximum of 100% that would represent no outage time in a typical monthly period. This is a measure of up or down status of connectivity, and is not intended to represent degraded service periods. This field MUST be in the file and MAY be populated. Name: uptime

Type/Format: numeric, range (0.0001,1.0000)

Examples: 0.9921, 1, 0.9899

\pagebreak

Appendix: CSV Schema for Machine-Readable Broadband Labels

For more information please see this reference page. 17

version 1.2 @totalColumns XXXX (number is TBD until we are done) (rest is TBD until fields defined) name: notEmpty field1: range(0, 120) field2: is("m") or is("f") or is("t") or is("n")

\pagebreak

Appendix: Sample Machine-Readable Broadband Label File

It should be possible to validate your file at https://digital-preservation.github.io/csv-validator/. HOLD UNTIL LATER

Footnotes

  1. See https://www.rfc-editor.org/info/rfc4180. ↩ ↩2

  2. See https://www.csvjson.com/csv2json. ↩

  3. https://www.rfc-editor.org/rfc/rfc6838.html ↩

  4. https://www.iana.org/assignments/media-types/text/csv ↩

  5. https://digital-preservation.github.io/csv-schema/csv-schema-1.2.html. ↩

  6. See https://www.iso.org/iso-8601-date-and-time-format.html. ↩ ↩2

  7. See https://www.fcc.gov/licensing-databases/commission-registration-system-fcc and https://www.fcc.gov/sites/default/files/form160.pdf. ↩ ↩2

  8. See https://www.iso.org/iso-3166-country-codes.html. ↩ ↩2

  9. See https://help.bdc.fcc.gov/hc/en-us/articles/5290793888795-Fixed-Technology-Codes. ↩

  10. See https://help.bdc.fcc.gov/hc/en-us/articles/6673022944155-Mobile-Technology-Codes. ↩

  11. See https://www.iso.org/iso-4217-currency-codes.html. This field MUST be in the file and MAY be populated. ↩

  12. See https://www.itu.int/rec/T-REC-E.164/. ↩

  13. See https://www.iana.org/assignments/as-numbers/as-numbers.xhtml. ↩

  14. See https://www.arin.net/resources/guide/asn/. ↩

  15. See https://ftp.arin.net/info/asn.txt. ↩

  16. https://www.iso.org/iso-639-language-code Name: language Type/Format: string, length(3) Examples: JPN, DEU, ITA ↩

  17. See https://digital-preservation.github.io/csv-schema/csv-schema-1.2.html. ↩