diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 19c2d6cab6..13c71af8f0 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10317,7 +10317,7 @@ table2-mapping
        <entry>
          Builds a JSON object out of a variadic argument list.  By
          convention, the argument list consists of alternating
-         names and values.
+         keys and values.
        </entry>
        <entry><literal>json_build_object('foo',1,'bar',2)</literal></entry>
        <entry><literal>{"foo": 1, "bar": 2}</literal></entry>
@@ -10329,9 +10329,9 @@ table2-mapping
        <entry>
          Builds a JSON object out of a text array.  The array must have either
          exactly one dimension with an even number of members, in which case
-         they are taken as alternating name/value pairs, or two dimensions
+         they are taken as alternating key/value pairs, or two dimensions
          such that each inner array has exactly two elements, which
-         are taken as a name/value pair.
+         are taken as a key/value pair.
        </entry>
        <entry><para><literal>json_object('{a, 1, b, "def", c, 3.5}')</></para>
         <para><literal>json_object('{{a, 1},{b, "def"},{c, 3.5}}')</></para></entry>
@@ -10715,9 +10715,9 @@ table2-mapping
       <function>json_to_record</> and <function>json_to_recordset</>,
       type coercion from the JSON is <quote>best effort</> and may not result
       in desired values for some types.  JSON keys are matched to
-      identical field names in the target row type, and fields that do
-      not exist in the JSON will simply be NULL.  JSON keys that do not
-      appear in the target row type will be omitted from the output.
+      identical column names in the target row type.  JSON fields that do not
+      appear in the target row type will be omitted from the output, and
+      target columns that do not match any JSON field will simply be NULL.
     </para>
   </note>
 
diff --git a/src/backend/utils/adt/json.c b/src/backend/utils/adt/json.c
index 5bd39f5015..9216511931 100644
--- a/src/backend/utils/adt/json.c
+++ b/src/backend/utils/adt/json.c
@@ -354,8 +354,9 @@ static void
 parse_object_field(JsonLexContext *lex, JsonSemAction *sem)
 {
 	/*
-	 * an object field is "fieldname" : value where value can be a scalar,
-	 * object or array
+	 * An object field is "fieldname" : value where value can be a scalar,
+	 * object or array.  Note: in user-facing docs and error messages, we
+	 * generally call a field name a "key".
 	 */
 
 	char	   *fname = NULL;	/* keep compiler quiet */
@@ -1890,7 +1891,6 @@ json_object_agg_transfn(PG_FUNCTION_ARGS)
 				(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
 				 errmsg("field name must not be null")));
 
-
 	val_type = get_fn_expr_argtype(fcinfo->flinfo, 1);
 
 	/*
@@ -1976,12 +1976,11 @@ json_build_object(PG_FUNCTION_ARGS)
 	StringInfo	result;
 	Oid			val_type;
 
-
 	if (nargs % 2 != 0)
 		ereport(ERROR,
 				(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
-				 errmsg("invalid number or arguments"),
-				 errhint("Object must be matched key value pairs.")));
+				 errmsg("argument list must have even number of elements"),
+				 errhint("The arguments of json_build_object() must consist of alternating keys and values.")));
 
 	result = makeStringInfo();
 
@@ -1989,7 +1988,6 @@ json_build_object(PG_FUNCTION_ARGS)
 
 	for (i = 0; i < nargs; i += 2)
 	{
-
 		/* process key */
 
 		if (PG_ARGISNULL(i))
@@ -2006,10 +2004,7 @@ json_build_object(PG_FUNCTION_ARGS)
 		if (val_type == UNKNOWNOID && get_fn_expr_arg_stable(fcinfo->flinfo, i))
 		{
 			val_type = TEXTOID;
-			if (PG_ARGISNULL(i))
-				arg = (Datum) 0;
-			else
-				arg = CStringGetTextDatum(PG_GETARG_POINTER(i));
+			arg = CStringGetTextDatum(PG_GETARG_POINTER(i));
 		}
 		else
 		{
@@ -2048,12 +2043,11 @@ json_build_object(PG_FUNCTION_ARGS)
 					 errmsg("could not determine data type for argument %d",
 							i + 2)));
 		add_json(arg, PG_ARGISNULL(i + 1), result, val_type, false);
-
 	}
+
 	appendStringInfoChar(result, '}');
 
 	PG_RETURN_TEXT_P(cstring_to_text_with_len(result->data, result->len));
-
 }
 
 /*
@@ -2127,9 +2121,8 @@ json_build_array_noargs(PG_FUNCTION_ARGS)
 /*
  * SQL function json_object(text[])
  *
- * take a one or two dimensional array of text as name vale pairs
+ * take a one or two dimensional array of text as key/value pairs
  * for a json object.
- *
  */
 Datum
 json_object(PG_FUNCTION_ARGS)
@@ -2219,7 +2212,7 @@ json_object(PG_FUNCTION_ARGS)
 /*
  * SQL function json_object(text[], text[])
  *
- * take separate name and value arrays of text to construct a json object
+ * take separate key and value arrays of text to construct a json object
  * pairwise.
  */
 Datum
@@ -2299,7 +2292,6 @@ json_object_two_arg(PG_FUNCTION_ARGS)
 	pfree(result.data);
 
 	PG_RETURN_TEXT_P(rval);
-
 }