maxmind-geoip2 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 874135d664c0af2e82c184ce30fffbdfe72bb6badc1aa53ee0ec5eba626e5a1d
-  data.tar.gz: 7aec662f3893322c983f647545f4a155b27bda20b7fd6349201fc386264bdc88
+  metadata.gz: 9c1d04d352a8344e1e8d9c232ab7713bc0b74ddaa1e4a82aec61dbbf37bfd925
+  data.tar.gz: 20bcee370b35a4e098b48b36146eb7da9674f6c271ba94744a435addbd9c5e05
 SHA512:
-  metadata.gz: 3b5d57920b467ccae6144b6f4aca8266721124481917014025390f02f6728138b704513137596593226506f82d554cf77afb215921a13fa8622e1b4e3a4f8b43
-  data.tar.gz: 28be946c7ea163e61b641029f3094de7b47ac2ce8bec6d1c68f9ddd5d084f55419403daeb30762fce3d0346ea0fb083de0d946621f6d659eabe03cafe3c3d0dd
+  metadata.gz: 0331f1fe319379d035bd4f8675f775bbe31f0d3747d2f9a65754523cb6718160237d5a232d54cad7cd00cdcfe5243ff0f8a39276d749948116fc974221eb3d8a
+  data.tar.gz: 1d3e2f6c9a5847671b4b86004c7407bacf25cb271674d7dd49c5217b15d20a307ba416ec19a5f04d2050925ee689a97f01ca899f2edcb611bb44c5ee1a13ba35

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.2.0 (2023-12-04)
+
+* `MaxMind::GeoIP2::Client` now validates the IP address before making a
+  request to the web service.
+* `MaxMind::GeoIP2::Client` now includes the version of Ruby, the version
+  of the HTTP client library, and its own version in the User-Agent header.
+* The `anycast?` method was added to `MaxMind::GeoIP2::Record::Traits`.
+  This returns `true` if the IP address belongs to an [anycast
+  network](https://en.wikipedia.org/wiki/Anycast). This is available for
+  the GeoIP2 Country, City Plus, and Insights web services and the GeoIP2
+  Country, City, and Enterprise databases.
+
+## 1.1.0 (2021-11-18)
+
+* Exceptions from this gem now inherit from `MaxMind::GeoIP2::Error`. IP
+  address related exceptions now inherit from
+  `MaxMind::GeoIP2::AddressError`, which itself inherits from
+  `MaxMind::GeoIP2::Error`. Pull Request by gr8bit. GitHub #35.
+* Support for mobile country code (MCC) and mobile network codes (MNC) was
+  added for the GeoIP2 ISP and Enterprise databases as well as the GeoIP2
+  City and Insights web services. `mobile_country_code` and
+  `mobile_network_code` attributes were added to
+  `MaxMind::GeoIP2::Model::ISP` for the GeoIP2 ISP database and
+  `MaxMind::GeoIP2::Record::Traits` for the Enterprise database and the
+  GeoIP2 City and Insights web services. We expect this data to be
+  available by late January, 2022.
+
 ## 1.0.0 (2021-05-14)
 
 * Ruby 2.4 is no longer supported. If you're using Ruby 2.4, please use

data/README.md

@@ -2,11 +2,9 @@
 
 ## Description
 
-This is the Ruby API for the GeoIP2
-[webservices](https://dev.maxmind.com/geoip/geoip2/web-services) and
-[databases](https://dev.maxmind.com/geoip/geoip2/geolite2/). This API also
-works with the free [GeoLite2
-databases](https://dev.maxmind.com/geoip/geoip2/geolite2/).
+This is the Ruby API for the GeoIP2 and GeoLite2
+[webservices](https://dev.maxmind.com/geoip/docs/web-services?lang=en)
+and [databases](https://dev.maxmind.com/geoip/docs/databases?lang=en).
 
 ## Installation
 
@@ -230,14 +228,19 @@ client = MaxMind::GeoIP2::Client.new(
   account_id: 42,
   license_key: 'license_key',
 
-  # To use the GeoLite2 web service instead of GeoIP2 Precision, set
+  # To use the GeoLite2 web service instead of the GeoIP2 web service, set
   # the host parameter to "geolite.info":
   # host: 'geolite.info',
+
+  # To use the Sandbox GeoIP2 web service instead of the production GeoIP2
+  # web service, set the host parameter to "sandbox.maxmind.com":
+  # host: 'sandbox.maxmind.com',
 )
 
 # Replace "city" with the method corresponding to the web service that
 # you are using, e.g., "country", "insights". Please note that Insights
-# is only supported by GeoIP2 Precision and not the GeoLite2 web service.
+# is only supported by the GeoIP2 web service and not the GeoLite2 web
+# service.
 record = client.city('128.101.101.101')
 
 puts record.country.iso_code # US
@@ -281,8 +284,8 @@ which can be populated vary between end points. In addition, while an end
 point may offer a particular piece of data, MaxMind does not always have
 every piece of data for any given IP address.
 
-See the [GeoIP2 Precision web service
-docs](https://dev.maxmind.com/geoip/geoip2/web-services) for details on
+See the [GeoIP2 web service
+documentation](https://dev.maxmind.com/geoip/docs/web-services?lang=en) for details on
 what data each end point may return.
 
 The only piece of data which is always returned is the `ip_address`
@@ -342,7 +345,7 @@ This library uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License
 
-This software is Copyright (c) 2020-2021 by MaxMind, Inc.
+This software is Copyright (c) 2020-2023 by MaxMind, Inc.
 
 This is free software, licensed under the [Apache License, Version
 2.0](LICENSE-APACHE) or the [MIT License](LICENSE-MIT), at your option.

data/lib/maxmind/geoip2/client.rb

@@ -4,15 +4,17 @@ require 'connection_pool'
 require 'http'
 require 'json'
 require 'maxmind/geoip2/errors'
+require 'maxmind/geoip2/version'
 require 'maxmind/geoip2/model/city'
 require 'maxmind/geoip2/model/country'
 require 'maxmind/geoip2/model/insights'
+require 'resolv'
 
 module MaxMind
   module GeoIP2
     # This class provides a client API for all the
-    # {https://dev.maxmind.com/geoip/geoip2/web-services/ GeoIP2 Precision web
-    # services}. The services are Country, City, and Insights. Each service
+    # {https://dev.maxmind.com/geoip/docs/web-services?lang=en GeoIP2 web
+    # services}. The services are Country, City Plus, and Insights. Each service
     # returns a different set of data about an IP address, with Country returning
     # the least data and Insights the most.
     #
@@ -58,7 +60,7 @@ module MaxMind
       # rubocop:disable Metrics/CyclomaticComplexity
       # rubocop:disable Metrics/PerceivedComplexity
 
-      # Create a Client that may be used to query a GeoIP2 Precision web service.
+      # Create a Client that may be used to query a GeoIP2 web service.
       #
       # Once created, the Client is safe to use for lookups from multiple
       # threads.
@@ -71,8 +73,10 @@ module MaxMind
       #   property from most preferred to least preferred.
       #
       # @param host [String] the host to use when querying the web service. Set
-      #   this to "geolite.info" to use the GeoLite2 web service instead of
-      #   GeoIP2 Precision.
+      #   this to "geolite.info" to use the GeoLite2 web service instead of the
+      #   GeoIP2 web service. Set this to "sandbox.maxmind.com" to use the
+      #   Sandbox environment. The sandbox allows you to experiment with the
+      #   API without affecting your production data.
       #
       # @param timeout [Integer] the number of seconds to wait for a request
       #   before timing out. If 0, no timeout is set.
@@ -117,7 +121,7 @@ module MaxMind
       # rubocop:enable Metrics/CyclomaticComplexity
       # rubocop:enable Metrics/ParameterLists
 
-      # This method calls the City web service.
+      # This method calls the City Plus web service.
       #
       # @param ip_address [String] IPv4 or IPv6 address as a string. If no
       #   address is provided, the address that the web service is called from is
@@ -193,8 +197,8 @@ module MaxMind
 
       # This method calls the Insights web service.
       #
-      # Insights is only supported by the GeoIP2 Precision web service. The
-      # GeoLite2 web service does not support it.
+      # Insights is only supported by the GeoIP2 web service. The GeoLite2 web
+      # service does not support it.
       #
       # @param ip_address [String] IPv4 or IPv6 address as a string. If no
       #   address is provided, the address that the web service is called from is
@@ -234,6 +238,10 @@ module MaxMind
       private
 
       def response_for(endpoint, model_class, ip_address)
+        if ip_address != 'me' && ip_address !~ Resolv::AddressRegex
+          raise AddressInvalidError, "The value \"#{ip_address}\" is not a valid IP address"
+        end
+
         record = get(endpoint, ip_address)
 
         model_class.new(record, @locales)
@@ -243,8 +251,9 @@ module MaxMind
         headers = HTTP.basic_auth(user: @account_id, pass: @license_key)
                       .headers(
                         accept: 'application/json',
-                        user_agent: 'MaxMind-GeoIP2-ruby',
+                        user_agent: "MaxMind-GeoIP2-ruby/#{VERSION} ruby/#{RUBY_VERSION} http/#{HTTP::VERSION}"
                       )
+
         timeout = @timeout > 0 ? headers.timeout(@timeout) : headers
 
         proxy = timeout

data/lib/maxmind/geoip2/errors.rb

@@ -2,40 +2,49 @@
 
 module MaxMind
   module GeoIP2
+    # Module's base error class
+    class Error < StandardError
+    end
+
+    # Base error class for all errors that originate from the IP address
+    # itself and will not change when retried.
+    class AddressError < Error
+    end
+
     # An AddressNotFoundError means the IP address was not found in the
     # database or the web service said the IP address was not found.
-    class AddressNotFoundError < RuntimeError
+    class AddressNotFoundError < AddressError
     end
 
     # An HTTPError means there was an unexpected HTTP status or response.
-    class HTTPError < RuntimeError
+    class HTTPError < Error
     end
 
     # An AddressInvalidError means the IP address was invalid.
-    class AddressInvalidError < RuntimeError
+    class AddressInvalidError < AddressError
     end
 
     # An AddressReservedError means the IP address is reserved.
-    class AddressReservedError < RuntimeError
+    class AddressReservedError < AddressError
     end
 
     # An AuthenticationError means there was a problem authenticating to the
     # web service.
-    class AuthenticationError < RuntimeError
+    class AuthenticationError < Error
     end
 
     # An InsufficientFundsError means the account is out of credits.
-    class InsufficientFundsError < RuntimeError
+    class InsufficientFundsError < Error
     end
 
     # A PermissionRequiredError means the account does not have permission to
     # use the requested service.
-    class PermissionRequiredError < RuntimeError
+    class PermissionRequiredError < Error
     end
 
     # An InvalidRequestError means the web service returned an error and there
     # is no more specific error class.
-    class InvalidRequestError < RuntimeError
+    class InvalidRequestError < Error
     end
   end
 end

data/lib/maxmind/geoip2/model/city.rb

@@ -9,12 +9,11 @@ require 'maxmind/geoip2/record/subdivision'
 module MaxMind
   module GeoIP2
     module Model
-      # Model class for the data returned by the GeoIP2 City web service and
-      # database. It is also used for GeoLite2 City lookups.
+      # Model class for the data returned by the GeoIP2 City Plus web service
+      # and the City database. It is also used for GeoLite2 City lookups.
       #
-      # The only difference between the City and Insights model classes is which
-      # fields in each record may be populated. See
-      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      # See https://dev.maxmind.com/geoip/docs/web-services?lang=en for more
+      # details.
       #
       # See {MaxMind::GeoIP2::Model::Country} for inherited methods.
       class City < Country

data/lib/maxmind/geoip2/model/connection_type.rb

@@ -7,8 +7,9 @@ module MaxMind
     module Model
       # Model class for the GeoIP2 Connection Type database.
       class ConnectionType < Abstract
-        # The connection type may take the following values: "Dialup", "Cable/DSL",
-        # "Corporate", "Cellular". Additional values may be added in the future.
+        # The connection type may take the following values: "Dialup",
+        # "Cable/DSL", "Corporate", "Cellular", and "Satellite". Additional
+        # values may be added in the future.
         #
         # @return [String, nil]
         def connection_type

data/lib/maxmind/geoip2/model/enterprise.rb

@@ -7,9 +7,8 @@ module MaxMind
     module Model
       # Model class for the data returned by GeoIP2 Enterprise database lookups.
       #
-      # The only difference between the City and Insights model classes is which
-      # fields in each record may be populated. See
-      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      # See https://dev.maxmind.com/geoip/docs/web-services?lang=en for more
+      # details.
       #
       # See {MaxMind::GeoIP2::Model::City} for inherited methods.
       class Enterprise < City

data/lib/maxmind/geoip2/model/insights.rb

@@ -5,12 +5,10 @@ require 'maxmind/geoip2/model/city'
 module MaxMind
   module GeoIP2
     module Model
-      # Model class for the data returned by the GeoIP2 Precision Insights web
-      # service.
+      # Model class for the data returned by the GeoIP2 Insights web service.
       #
-      # The only difference between the City and Insights model classes is which
-      # fields in each record may be populated. See
-      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      # See https://dev.maxmind.com/geoip/docs/web-services?lang=en for more
+      # details.
       class Insights < City
       end
     end

data/lib/maxmind/geoip2/model/isp.rb

@@ -36,6 +36,22 @@ module MaxMind
           get('isp')
         end
 
+        # The {https://en.wikipedia.org/wiki/Mobile_country_code mobile country
+        # code (MCC)} associated with the IP address and ISP.
+        #
+        # @return [String, nil]
+        def mobile_country_code
+          get('mobile_country_code')
+        end
+
+        # The {https://en.wikipedia.org/wiki/Mobile_country_code mobile network
+        # code (MNC)} associated with the IP address and ISP.
+        #
+        # @return [String, nil]
+        def mobile_network_code
+          get('mobile_network_code')
+        end
+
         # The network in CIDR notation associated with the record. In particular,
         # this is the largest network where all of the fields besides ip_address
         # have the same value.

data/lib/maxmind/geoip2/reader.rb

@@ -37,8 +37,7 @@ module MaxMind
       # Reader and reuse it.
       #
       # Once created, the Reader is safe to use for lookups from multiple
-      # threads. It is safe to use after forking only if you use
-      # MaxMind::DB::MODE_MEMORY or if your version of Ruby supports IO#pread.
+      # threads. It is safe to use after forking.
       #
       # @overload initialize(database:, locales: ['en'], mode: MaxMind::DB::MODE_AUTO)
       #   @param database [String] a path to a GeoIP2/GeoLite2 database file.

data/lib/maxmind/geoip2/record/traits.rb

@@ -16,16 +16,14 @@ module MaxMind
           if record && !record.key?('network') && record.key?('ip_address') &&
              record.key?('prefix_length')
             ip = IPAddr.new(record['ip_address']).mask(record['prefix_length'])
-            # We could use ip.prefix instead of record['prefix_length'], but that
-            # method only becomes available in Ruby 2.5+.
-            record['network'] = format('%s/%d', ip.to_s, record['prefix_length'])
+            record['network'] = format('%s/%d', ip.to_s, ip.prefix)
           end
         end
 
         # The autonomous system number associated with the IP address. See
         # Wikipedia[https://en.wikipedia.org/wiki/Autonomous_system_(Internet)].
-        # This attribute is only available from the City and Insights web service
-        # and the GeoIP2 Enterprise database.
+        # This attribute is only available from the City Plus and Insights web
+        # services and the Enterprise database.
         #
         # @return [Integer, nil]
         def autonomous_system_number
@@ -35,8 +33,8 @@ module MaxMind
         # The organization associated with the registered autonomous system number
         # for the IP address. See
         # Wikipedia[https://en.wikipedia.org/wiki/Autonomous_system_(Internet)].
-        # This attribute is only available from the City and Insights web service
-        # and the GeoIP2 Enterprise database.
+        # This attribute is only available from the City Plus and Insights web
+        # services and the Enterprise database.
         #
         # @return [String, nil]
         def autonomous_system_organization
@@ -44,8 +42,9 @@ module MaxMind
         end
 
         # The connection type may take the following  values: "Dialup",
-        # "Cable/DSL", "Corporate", "Cellular". Additional values may be added in
-        # the future. This attribute is only available in the GeoIP2 Enterprise
+        # "Cable/DSL", "Corporate", "Cellular", and "Satellite". Additional
+        # values may be added in the future. This attribute is only available
+        # from the City Plus and Insights web services and the Enterprise
         # database.
         #
         # @return [String, nil]
@@ -55,8 +54,8 @@ module MaxMind
 
         # The second level domain associated with the IP address. This will be
         # something like "example.com" or "example.co.uk", not "foo.example.com".
-        # This attribute is only available from the City and Insights web service
-        # and the GeoIP2 Enterprise database.
+        # This attribute is only available from the City Plus and Insights web
+        # services and the Enterprise database.
         #
         # @return [String, nil]
         def domain
@@ -75,7 +74,7 @@ module MaxMind
         end
 
         # This is true if the IP address belongs to any sort of anonymous network.
-        # This property is only available from GeoIP2 Precision Insights.
+        # This property is only available from Insights.
         #
         # @return [Boolean]
         def anonymous?
@@ -85,17 +84,28 @@ module MaxMind
         # This is true if the IP address is registered to an anonymous VPN
         # provider. If a VPN provider does not register subnets under names
         # associated with them, we will likely only flag their IP ranges using the
-        # hosting_provider? property. This property is only available from GeoIP2
-        # Precision Insights.
+        # hosting_provider? property. This property is only available from Insights.
         #
         # @return [Boolean]
         def anonymous_vpn?
           get('is_anonymous_vpn')
         end
 
+        # This is true if the IP address belongs to an
+        # {https://en.wikipedia.org/wiki/Anycast anycast network}.
+        #
+        # This property is only available from the Country, City Plus, and
+        # Insights web services and the GeoIP2 Country, City, and Enterprise
+        # databases.
+        #
+        # @return [Boolean]
+        def anycast?
+          get('is_anycast')
+        end
+
         # This is true if the IP address belongs to a hosting or VPN provider (see
         # description of the anonymous_vpn? property). This property is only
-        # available from GeoIP2 Precision Insights.
+        # available from Insights.
         #
         # @return [Boolean]
         def hosting_provider?
@@ -104,15 +114,37 @@ module MaxMind
 
         # This attribute is true if MaxMind believes this IP address to be a
         # legitimate proxy, such as an internal VPN used by a corporation. This
-        # attribute is only available in the GeoIP2 Enterprise database.
+        # attribute is only available in the Enterprise database.
         #
         # @return [Boolean]
         def legitimate_proxy?
           get('is_legitimate_proxy')
         end
 
+        # The {https://en.wikipedia.org/wiki/Mobile_country_code mobile country
+        # code (MCC)} associated with the IP address and ISP.
+        #
+        # This attribute is only available from the City Plus and Insights web
+        # services and the Enterprise database.
+        #
+        # @return [String, nil]
+        def mobile_country_code
+          get('mobile_country_code')
+        end
+
+        # The {https://en.wikipedia.org/wiki/Mobile_country_code mobile network
+        # code (MNC)} associated with the IP address and ISP.
+        #
+        # This attribute is only available from the City Plus and Insights web
+        # services and the Enterprise database.
+        #
+        # @return [String, nil]
+        def mobile_network_code
+          get('mobile_network_code')
+        end
+
         # This is true if the IP address belongs to a public proxy. This property
-        # is only available from GeoIP2 Precision Insights.
+        # is only available from Insights.
         #
         # @return [Boolean]
         def public_proxy?
@@ -121,7 +153,7 @@ module MaxMind
 
         # This is true if the IP address is on a suspected anonymizing network
         # and belongs to a residential ISP. This property is only available
-        # from GeoIP2 Precision Insights.
+        # from Insights.
         #
         # @return [Boolean]
         def residential_proxy?
@@ -129,7 +161,7 @@ module MaxMind
         end
 
         # This is true if the IP address is a Tor exit node. This property is only
-        # available from GeoIP2 Precision Insights.
+        # available from Insights.
         #
         # @return [Boolean]
         def tor_exit_node?
@@ -137,7 +169,7 @@ module MaxMind
         end
 
         # The name of the ISP associated with the IP address. This attribute is
-        # only available from the City and Insights web services and the GeoIP2
+        # only available from the City Plus and Insights web services and the
         # Enterprise database.
         #
         # @return [String, nil]
@@ -155,8 +187,8 @@ module MaxMind
         end
 
         # The name of the organization associated with the IP address. This
-        # attribute is only available from the City and Insights web services and
-        # the GeoIP2 Enterprise database.
+        # attribute is only available from the City Plus and Insights web services
+        # and the Enterprise database.
         #
         # @return [String, nil]
         def organization
@@ -164,7 +196,7 @@ module MaxMind
         end
 
         # An indicator of how static or dynamic an IP address is. This property is
-        # only available from GeoIP2 Precision Insights.
+        # only available from Insights.
         #
         # @return [Float, nil]
         def static_ip_score
@@ -173,8 +205,7 @@ module MaxMind
 
         # The estimated number of users sharing the IP/network during the past 24
         # hours. For IPv4, the count is for the individual IP. For IPv6, the count
-        # is for the /64 network. This property is only available from GeoIP2
-        # Precision Insights.
+        # is for the /64 network. This property is only available from Insights.
         #
         # @return [Integer, nil]
         def user_count
@@ -188,6 +219,7 @@ module MaxMind
         # * cafe
         # * cellular
         # * college
+        # * consumer_privacy_network
         # * content_delivery_network
         # * dialup
         # * government
@@ -201,7 +233,7 @@ module MaxMind
         # * traveler
         #
         # This attribute is only available from the Insights web service and the
-        # GeoIP2 Enterprise database.
+        # Enterprise database.
         #
         # @return [String, nil]
         def user_type

data/lib/maxmind/geoip2/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module MaxMind
+  module GeoIP2
+    # The Gem version.
+    VERSION = '1.2.0'
+  end
+end

data/maxmind-geoip2.gemspec

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'maxmind/geoip2/version'
+
 Gem::Specification.new do |s|
   s.authors     = ['William Storey']
   s.files       = Dir['**/*']
   s.name        = 'maxmind-geoip2'
   s.summary     = 'A gem for interacting with the GeoIP2 webservices and databases.'
-  s.version     = '1.0.0'
+  s.version     = MaxMind::GeoIP2::VERSION
 
   s.description = 'A gem for interacting with the GeoIP2 webservices and databases. MaxMind provides geolocation data as downloadable databases as well as through a webservice.'
   s.email = 'support@maxmind.com'
@@ -16,13 +21,14 @@ Gem::Specification.new do |s|
     'changelog_uri' => 'https://github.com/maxmind/GeoIP2-ruby/blob/main/CHANGELOG.md',
     'documentation_uri' => 'https://www.rubydoc.info/gems/maxmind-geoip2',
     'homepage_uri' => 'https://github.com/maxmind/GeoIP2-ruby',
+    'rubygems_mfa_required' => 'true',
     'source_code_uri' => 'https://github.com/maxmind/GeoIP2-ruby',
   }
   s.required_ruby_version = '>= 2.5.0'
 
   s.add_runtime_dependency 'connection_pool', ['~> 2.2']
   s.add_runtime_dependency 'http', '>= 4.3', '< 6.0'
-  s.add_runtime_dependency 'maxmind-db', ['~> 1.1']
+  s.add_runtime_dependency 'maxmind-db', ['~> 1.2']
 
   s.add_development_dependency 'minitest'
   s.add_development_dependency 'rake'

data/test/data/MaxMind-DB-spec.md

@@ -26,9 +26,10 @@ not be broken by minor version changes to the format.
 The binary database is split into three parts:
 
 1. The binary search tree. Each level of the tree corresponds to a single bit
-in the 128 bit representation of an IPv6 address.
-2. The data section. These are the values returned to the client for a
-specific IP address, e.g. "US", "New York", or a more complex map type made up
+in the prefix of the network the IP address belongs to.
+2. The data section with the values for the networks in the binary search
+tree. These values may be comprised of a single data type, e.g., the string
+"US" or "New York", or they may be a more complex map or array type made up
 of multiple fields.
 3. Database metadata. Information about the database itself.
 
@@ -48,15 +49,15 @@ of this sequence.
 The maximum allowable size for the metadata section, including the marker that
 starts the metadata, is 128KiB.
 
-The metadata is stored as a map data structure. This structure is described
-later in the spec. Changing a key's data type or removing a key would
-constitute a major version change for this spec.
+The metadata is stored as a separate data section comprised of a map data
+structure starting at the beginning of that section. This structure is
+described later in the spec.
 
 Except where otherwise specified, each key listed is required for the database
 to be considered valid.
 
-Adding a key constitutes a minor version change. Removing a key or changing
-its type constitutes a major version change.
+Changing a key's data type or removing a key would constitute a major version
+change for this spec. Adding a key constitutes a minor version change.
 
 The list of known keys for the current version of the format is as follows:
 
@@ -304,7 +305,8 @@ will point to the beginning of a field. It is illegal for a pointer to point
 to another pointer.
 
 Pointer values start from the beginning of the data section, *not* the
-beginning of the file.
+beginning of the file. Pointers in the metadata start from the beginning of
+the metadata section.
 
 ### UTF-8 string - 2
 
@@ -337,8 +339,10 @@ by the length specifier in the control byte. See below for details.
 
 A length of zero always indicates the number 0.
 
-When storing a signed integer, the left-most bit is the sign. A 1 is negative
-and a 0 is positive.
+When storing a signed integer, fields shorter than the maximum byte length
+are always positive. When the field is the maximum length, e.g., 4 bytes for
+32-bit integers, the left-most bit is the sign. A 1 is negative and a 0 is
+positive.
 
 The type numbers for our integer types are: